@dxos/assistant-toolkit 0.8.4-main.74a063c4e0 → 0.8.4-main.765dc60934

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

@@ -6,61 +6,64 @@ 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 { AiSession, ToolExecutionServices } from '@dxos/assistant';
+import { Operation } from '@dxos/compute';
 import { Database, Feed, Obj } from '@dxos/echo';
 import { acquireReleaseResource } from '@dxos/effect';
 import { invariant } from '@dxos/invariant';
-import { Operation } from '@dxos/operation';
+import { ContentBlock } from '@dxos/types';
 
-import { Project } from '../../../types';
-import { Agent } from './definitions';
+import { Agent } from '../../../types';
+import { AgentWorker } from './definitions';
 
-export default Agent.pipe(
+export default AgentWorker.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.');
+    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 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 chatFeed = yield* agent.chat.pipe(
+        Database.load,
+        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.Session({ 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 (!prompt && !event) {
-          throw new Error('Either prompt or event must be provided.');
-        }
+      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`;
-        }
+      let input: ContentBlock.Any[] = [];
+      if (prompt) {
+        input.push({ _tag: 'text', text: prompt, disposition: 'synthetic' });
+      }
+      if (event) {
+        input.push({ _tag: 'text', text: JSON.stringify(event), disposition: 'synthetic' });
+      }
 
-        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),
-        ),
-      ),
-    ),
+      yield* session
+        .createRequest({
+          prompt: input,
+        })
+        .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

@@ -4,23 +4,22 @@
 
 import * as Schema from 'effect/Schema';
 
-import { AiService, GenericToolkit } from '@dxos/ai';
-import { AiContextService } from '@dxos/assistant';
+import { AiService, OpaqueToolkit } from '@dxos/ai';
+import { AiContext } from '@dxos/assistant';
+import { Trace, TriggerEvent, Operation, OperationRegistry } from '@dxos/compute';
 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 { QueueService } from '@dxos/functions';
 
-import { Project } from '../../../types';
+import { Agent } from '../../../types';
 
-export const Agent = Operation.make({
+export const AgentWorker = Operation.make({
   meta: {
-    key: 'org.dxos.function.project.agent',
-    name: 'Project Agent',
-    description: 'Agentic worker that drives the project autonomously.',
+    key: 'org.dxos.function.agent.worker',
+    name: 'Agent Worker',
+    description: 'Agentic worker that drives the agent autonomously.',
   },
   input: Schema.Struct({
-    project: Schema.suspend(() => Ref.Ref(Project.Project)),
+    agent: Schema.suspend(() => Ref.Ref(Agent.Agent)),
     prompt: Schema.optional(Schema.String),
     event: Schema.optional(TriggerEvent.TriggerEvent),
   }),
@@ -31,39 +30,37 @@ export const Agent = Operation.make({
     QueueService,
     Feed.FeedService,
     OperationRegistry.Service,
-    // @deprecated TracingService kept for backward compat with tool handlers.
-    TracingService,
     Trace.TraceService,
-    GenericToolkit.GenericToolkitProvider,
+    OpaqueToolkit.OpaqueToolkitProvider,
   ],
-});
+}).pipe(Operation.intrinsic);
 
 export const Qualifier = Operation.make({
   meta: {
-    key: 'org.dxos.function.project.qualifier',
-    name: 'Project Qualifier',
+    key: 'org.dxos.function.agent.qualifier',
+    name: 'Agent Qualifier',
     description:
-      'Qualifier that determines if the event is relevant to the project. Puts the data into the input queue of the project.',
+      'Qualifier that determines if the event is relevant to the agent. Puts the data into the input queue of the agent.',
   },
   input: Schema.Struct({
-    project: Schema.suspend(() => Ref.Ref(Project.Project)),
+    agent: Schema.suspend(() => Ref.Ref(Agent.Agent)),
     event: TriggerEvent.TriggerEvent,
   }),
   output: Schema.Void,
-  services: [AiService.AiService, Database.Service],
-});
+  services: [AiService.AiService, Database.Service, Feed.FeedService],
+}).pipe(Operation.intrinsic);
 
 export const GetContext = Operation.make({
   meta: {
-    key: 'org.dxos.function.project.get-context',
-    name: 'Get Project Context',
-    description: 'Get the context of an project.',
+    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,
-    spec: Schema.String,
+    instructions: Schema.String,
     plan: Schema.String,
     artifacts: Schema.Array(
       Schema.Struct({
@@ -73,12 +70,12 @@ export const GetContext = Operation.make({
       }),
     ),
   }),
-  services: [AiContextService, Database.Service],
-});
+  services: [AiContext.Service, Database.Service],
+}).pipe(Operation.intrinsic);
 
 export const AddArtifact = Operation.make({
   meta: {
-    key: 'org.dxos.function.project.add-artifact',
+    key: 'org.dxos.function.agent.add-artifact',
     name: 'Add artifact',
     description: 'Adds a new artifact.',
   },
@@ -91,5 +88,5 @@ export const AddArtifact = Operation.make({
     }),
   }),
   output: Schema.Void,
-  services: [AiContextService, Database.Service],
-});
+  services: [AiContext.Service, Database.Service],
+}).pipe(Operation.intrinsic);

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

@@ -4,31 +4,31 @@
 
 import * as Effect from 'effect/Effect';
 
+import { Operation } from '@dxos/compute';
 import { Database, Obj } from '@dxos/echo';
-import { Operation } from '@dxos/operation';
 
-import { Plan, Project } from '../../../types';
+import { Plan, Agent } from '../../../types';
 import { GetContext } from './definitions';
 
 export default GetContext.pipe(
   Operation.withHandler(
     Effect.fnUntraced(function* () {
-      const project = yield* Project.getFromChatContext;
+      const agent = yield* Agent.getFromChatContext;
 
       return {
-        id: project.id,
-        name: project.name,
-        spec: yield* project.spec.pipe(Database.load).pipe(
+        id: agent.id,
+        name: agent.name,
+        instructions: yield* agent.instructions.pipe(Database.load).pipe(
           Effect.map((_) => _.content),
-          Effect.catchTag('ObjectNotFoundError', () => Effect.succeed('No spec found.')),
+          Effect.catchTag('ObjectNotFoundError', () => Effect.succeed('No instructions found.')),
         ),
         plan: yield* (
-          project.plan?.pipe(Database.load).pipe(
+          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(project.artifacts, (artifact) =>
+        artifacts: yield* Effect.forEach(agent.artifacts, (artifact) =>
           Effect.gen(function* () {
             return {
               name: artifact.name,
@@ -43,4 +43,5 @@ export default GetContext.pipe(
       };
     }) as any,
   ),
+  Operation.opaqueHandler,
 );

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

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

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

@@ -8,29 +8,29 @@ 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 { Operation } from '@dxos/compute';
+import { Database, Feed, 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 { Plan, Agent } 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.');
+      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;
+        const { id, name, feed: queue } = agent;
         if (!queue) {
-          throw new Error('Project has no 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 } = yield* Effect.scoped(
           LanguageModel.generateObject({
@@ -40,18 +40,18 @@ export default Qualifier.pipe(
             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.
+                  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.
-                  <project id="${id}" name="${name}">
-                    <spec>
-                    ${spec.content}
-                    </spec>
+                  <agent id="${id}" name="${name}">
+                    <instructions>
+                    ${instructions.content}
+                    </instructions>
                     <plan>
                       ${Plan.formatPlan(plan)}
                     </plan>
-                  </project>
+                  </agent>
                 `,
               }),
               Prompt.userMessage({
@@ -72,13 +72,13 @@ export default Qualifier.pipe(
         const { isRelevant } = value as { isRelevant: boolean };
 
         if (isRelevant) {
-          const queueTarget = yield* Database.load(queue);
+          const feedTarget = yield* Database.load(queue);
           if ('queue' in event && event.item) {
             const obj = event.item;
-            yield* Effect.promise(() => queueTarget.append([obj]));
+            yield* Feed.append(feedTarget, [obj]);
           } else if ('subject' in event && Ref.isRef(event.subject)) {
             const obj = yield* Database.load(event.subject);
-            yield* Effect.promise(() => queueTarget.append([obj]));
+            yield* Feed.append(feedTarget, [obj]);
           } else {
             throw new Error('Invalid event.');
           }

package/src/blueprints/project/index.ts

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

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

@@ -2,45 +2,49 @@
 // Copyright 2026 DXOS.org
 //
 
-import { type AppCapabilities } from '@dxos/app-toolkit';
-import { Blueprint, Template } from '@dxos/blueprints';
+import { Blueprint, Template } from '@dxos/compute';
 import { trim } from '@dxos/util';
 
-import { ProjectRules, CreateProject, SyncTriggers } from './functions';
+import { AgentRules, CreateAgent, SyncTriggers } from './functions';
 
-const BLUEPRINT_KEY = 'org.dxos.blueprint.project-wizard';
+const BLUEPRINT_KEY = 'org.dxos.blueprint.agent-wizard';
 
 /**
- * Creates the Project blueprint. This is a function to avoid circular dependency issues.
+ * Creates the Agent Wizard blueprint. This is a function to avoid circular dependency issues.
  */
-// TODO(dmaretskyi): Combine with Project Blueprint
+// TODO(dmaretskyi): Combine with Agent Blueprint.
 const make = () =>
   Blueprint.make({
     key: BLUEPRINT_KEY,
-    name: 'Project Wizard',
-    description: 'Help the user create a new project.',
+    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 project.
+        You are a wizard that helps the user create a new agent.
 
-        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.
+        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.
 
-        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.
+        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.
 
-        IMPORTANT: Before attempting to create a project call the [project-rules] tool to get the rules for creating a project.
+        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: [ProjectRules, CreateProject, SyncTriggers] }),
+    tools: Blueprint.toolDefinitions({ operations: [AgentRules, CreateAgent, SyncTriggers] }),
   });
 
-const blueprint: AppCapabilities.BlueprintDefinition = {
+const blueprint: Blueprint.Definition = {
   key: BLUEPRINT_KEY,
   make,
 };

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

@@ -4,30 +4,29 @@
 
 import * as Effect from 'effect/Effect';
 
-import { Blueprint } from '@dxos/blueprints';
+import { Blueprint, Operation } from '@dxos/compute';
 import { Obj, Ref } from '@dxos/echo';
-import { Operation } from '@dxos/operation';
 
-import { Project } from '../../../types';
-import { ProjectBlueprint } from '../../project';
-import { CreateProject, SyncTriggers } from './definitions';
+import { Agent } from '../../../types';
+import { AgentBlueprint } from '../../project';
+import { CreateAgent, SyncTriggers } from './definitions';
 
-export default CreateProject.pipe(
+export default CreateAgent.pipe(
   Operation.withHandler(
-    Effect.fnUntraced(function* ({ name, spec, blueprints, subscriptions }) {
-      const project = yield* Project.makeInitialized(
+    Effect.fnUntraced(function* ({ name, instructions, blueprints, subscriptions }) {
+      const agent = yield* Agent.makeInitialized(
         {
           name,
-          spec,
+          instructions,
           blueprints: yield* Effect.forEach(blueprints, (key) =>
             Blueprint.upsert(key).pipe(Effect.map(Ref.make), Effect.orDie),
           ),
           subscriptions,
         },
-        Obj.clone(ProjectBlueprint.make()),
+        Obj.clone(AgentBlueprint.make()),
       );
-      yield* Operation.invoke(SyncTriggers, { project: Ref.make(project) });
-      return project;
+      yield* Operation.invoke(SyncTriggers, { agent: Ref.make(agent) });
+      return agent;
     }),
   ),
 );

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

@@ -4,59 +4,58 @@
 
 import * as Schema from 'effect/Schema';
 
-import { Blueprint } from '@dxos/blueprints';
+import { Blueprint, Operation } from '@dxos/compute';
 import { Database, Feed, Obj, Ref } from '@dxos/echo';
 import { QueueService } from '@dxos/functions';
-import { Operation } from '@dxos/operation';
 
-import { Project } from '../../../types';
+import { Agent } from '../../../types';
 
-export const ProjectRules = Operation.make({
+export const AgentRules = Operation.make({
   meta: {
-    key: 'org.dxos.function.project-wizard.project-rules',
-    name: 'Project rules',
-    description: 'Gets the rules for creating a project.',
+    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 CreateProject = Operation.make({
+export const CreateAgent = Operation.make({
   meta: {
-    key: 'org.dxos.function.project-wizard.create-project',
-    name: 'Create project',
-    description: 'Creates a new project.',
+    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 project to create.',
+      description: 'The name of the agent to create.',
     }),
-    spec: Schema.String.annotations({
+    instructions: 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.',
+        '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 keys blueprints to use for the project.',
+      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 project. Can be references to mailboxes.',
+      description: 'The objects to subscribe to for the agent. Can be references to mailboxes.',
     }),
   }),
-  output: Project.Project,
+  output: Agent.Agent,
   services: [Blueprint.RegistryService, Database.Service, QueueService, Feed.FeedService],
 });
 
 export const SyncTriggers = Operation.make({
   meta: {
-    key: 'org.dxos.function.project.sync-triggers',
+    key: 'org.dxos.function.agent.sync-triggers',
     name: 'Sync triggers',
     description:
-      'Synchronizes triggers in the database with the project subscriptions. Call this after editing the subscriptions array.',
+      'Synchronizes triggers with the agent: subscriptions, cron, filter-events, and enabled (copied to every trigger). Call after editing those fields.',
   },
   input: Schema.Struct({
-    project: Ref.Ref(Project.Project).annotations({
-      description: 'The project whose triggers should be synced.',
+    agent: Ref.Ref(Agent.Agent).annotations({
+      description: 'The agent whose triggers should be synced.',
     }),
   }),
   output: Schema.Void,

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

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