@dxos/assistant-toolkit 0.8.4-main.9735255 → 0.8.4-main.abd8ff62ef

package/src/{initiative/initiative.test.ts → blueprints/project/blueprint.test.ts}

@@ -2,64 +2,148 @@
 // Copyright 2025 DXOS.org
 //
 
-import { describe, it } from '@effect/vitest';
+import { describe, expect, it } from '@effect/vitest';
 import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
 
 import { MemoizedAiService } from '@dxos/ai/testing';
-import { AiConversation } from '@dxos/assistant';
-import { AssistantTestLayerWithTriggers } from '@dxos/assistant/testing';
-import { Blueprint } from '@dxos/blueprints';
-import { Database, Obj, Ref } from '@dxos/echo';
+import { AiSession } from '@dxos/assistant';
+import { SpaceProperties } from '@dxos/client-protocol';
+import { Blueprint, Trigger, Operation, OperationHandlerSet } from '@dxos/compute';
+import { Database, Feed, Filter, Obj, Query, Ref } from '@dxos/echo';
+import { Collection } from '@dxos/echo';
 import { acquireReleaseResource } from '@dxos/effect';
 import { TestHelpers } from '@dxos/effect/testing';
-import { FunctionDefinition, QueueService, Trigger } from '@dxos/functions';
+import { QueueService } from '@dxos/functions';
 import { TriggerDispatcher } from '@dxos/functions-runtime';
+import { AssistantTestLayerWithTriggers } from '@dxos/functions-runtime/testing';
 import { invariant } from '@dxos/invariant';
 import { ObjectId } from '@dxos/keys';
+import { MarkdownBlueprint } from '@dxos/plugin-markdown/blueprints';
+import { MarkdownOperationHandlerSet } from '@dxos/plugin-markdown/operations';
+import { WithProperties } from '@dxos/plugin-markdown/testing';
+import { Markdown } from '@dxos/plugin-markdown/types';
 import { Text } from '@dxos/schema';
 import { Message } from '@dxos/types';
 import { trim } from '@dxos/util';
 
-import { agent } from './functions';
-import * as Initiative from './Initiative';
+import { Chat, Plan, Agent } from '../../types';
+import { PlanningBlueprint, PlanningHandlers } from '../planning';
+import { AgentWizardHandlers, SyncTriggers } from '../project-wizard';
+import AgentBlueprintDef from './blueprint';
+import { AgentWorker, AgentBlueprintHandlers } from './functions';
 
 ObjectId.dangerouslyDisableRandomness();
 
 const TestLayer = AssistantTestLayerWithTriggers({
   aiServicePreset: 'edge-remote',
-  functions: [...Initiative.functions],
-  types: [Initiative.Initiative, Blueprint.Blueprint, Trigger.Trigger, Text.Text],
+  operationHandlers: OperationHandlerSet.merge(
+    AgentBlueprintHandlers,
+    AgentWizardHandlers,
+    MarkdownOperationHandlerSet,
+    PlanningHandlers,
+  ),
+  types: [
+    Agent.Agent,
+    Plan.Plan,
+    Chat.CompanionTo,
+    Chat.Chat,
+    SpaceProperties,
+    Blueprint.Blueprint,
+    Trigger.Trigger,
+    Text.Text,
+    Markdown.Document,
+    Collection.Collection,
+  ],
   tracing: 'pretty',
 });
 
 const SYSTEM = trim`
-  If you do not have tools to complete the task, inform the user. DO NOT PRETEND TO DO SOMETHING YOU CAN'T DO.
+  You are a helpful assistant that can help with tasks in the outside world.
+  Be transparent about what you are doing and what you are not doing.
+  If you do not have tools to complete the task, inform the user.
+  DO NOT PRETEND TO DO SOMETHING YOU CAN'T DO.
 `;
 
-describe('Initiative', () => {
+describe('Agent', () => {
+  const blueprint = AgentBlueprintDef.make();
+
   it.scoped(
-    'shopping list',
+    'agent adds artifact to agent',
     Effect.fnUntraced(
       function* (_) {
-        const initiative = yield* Database.Service.add(
-          yield* Initiative.make({
-            name: 'Shopping list',
-            spec: 'Keep a shopping list of items to buy.',
-          }),
+        const agent = yield* Agent.makeInitialized(
+          {
+            name: 'Test Project',
+            instructions: 'A test project for adding artifacts.',
+            blueprints: [Ref.make(MarkdownBlueprint.make())],
+          },
+          blueprint,
         );
-        invariant(initiative.chat?.target, 'Initiative chat queue not found.');
-        yield* Database.Service.flush({ indexes: true });
-        const conversation = yield* acquireReleaseResource(
-          () => new AiConversation({ queue: initiative.chat?.target as any }),
-        );
-        yield* Effect.promise(() => conversation.context.open());
+        yield* Database.flush();
 
-        yield* conversation.createRequest({
-          system: SYSTEM,
-          prompt: `List ingredients for a scrambled eggs on a toast breakfast.`,
-        });
+        const document = yield* Database.add(
+          Obj.make(Markdown.Document, {
+            name: 'Test Document',
+            content: Ref.make(Text.make('This is a test document with some content.')),
+          }),
+        );
+        yield* Database.flush();
+
+        expect(agent.artifacts).toHaveLength(0);
+
+        const chatFeed = agent.chat?.target?.feed?.target;
+        invariant(chatFeed, 'Agent chat feed not found.');
+        const runtime = yield* Effect.runtime<Feed.FeedService>();
+        const session = yield* acquireReleaseResource(() => new AiSession({ feed: chatFeed, runtime }));
+        yield* Effect.promise(() => session.context.open());
+
+        const documentDxn = Obj.getDXN(document);
+        yield* session
+          .createRequest({
+            system: SYSTEM,
+            prompt: `Please add the document ${documentDxn} as an artifact named "My Test Document" to this agent.`,
+          })
+          .pipe(Effect.provide(session.makeToolExecutionServices()));
+
+        expect(agent.artifacts).toHaveLength(1);
+        expect(agent.artifacts[0].name).toBe('My Test Document');
+        const artifactData = yield* agent.artifacts[0].data.pipe(Database.load);
+        expect(Obj.instanceOf(Markdown.Document, artifactData)).toBe(true);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+    MemoizedAiService.isGenerationEnabled() ? 240_000 : 30_000,
+  );
 
-        console.log(yield* Effect.promise(() => dumpInitiative(initiative)));
+  it.scoped(
+    'shopping list',
+    Effect.fnUntraced(
+      function* (_) {
+        const agent = yield* Agent.makeInitialized(
+          {
+            name: 'Shopping list',
+            instructions: 'Keep a shopping list of items to buy.',
+            blueprints: [Ref.make(MarkdownBlueprint.make())],
+          },
+          blueprint,
+        );
+        const chatFeed = agent.chat?.target?.feed?.target;
+        invariant(chatFeed, 'Agent chat feed not found.');
+        yield* Database.flush();
+        const runtime = yield* Effect.runtime<Feed.FeedService>();
+        const session = yield* acquireReleaseResource(() => new AiSession({ feed: chatFeed, runtime }));
+        yield* Effect.promise(() => session.context.open());
+
+        yield* session
+          .createRequest({
+            system: SYSTEM,
+            prompt: `List ingredients for a scrambled eggs on a toast breakfast.`,
+          })
+          .pipe(Effect.provide(session.makeToolExecutionServices()));
+
+        console.log(yield* Effect.promise(() => dumpAgent(agent)));
       },
       Effect.provide(TestLayer),
       TestHelpers.provideTestContext,
@@ -71,35 +155,33 @@ describe('Initiative', () => {
     'expense tracking list',
     Effect.fnUntraced(
       function* (_) {
-        const initiative = yield* Database.Service.add(
-          yield* Initiative.make({
+        const agent = yield* Agent.makeInitialized(
+          {
             name: 'Expense tracking',
-            spec: trim`
+            instructions: trim`
               Keep a list of expenses in a markdown document (create artifact "Expenses").
               Process incoming emails, add the relevant ones to the list.
 
               Format:
 
-              ## Expences
-
+              ## Expenses
               - Flight to London (2026-02-01): £100
               - Hotel in London (2026-02-01): £100
             `,
-          }),
+            blueprints: [Ref.make(MarkdownBlueprint.make())],
+          },
+          blueprint,
         );
-        yield* Database.Service.flush({ indexes: true });
+        yield* Database.flush();
 
         const inboxQueue = yield* QueueService.createQueue();
-        yield* Database.Service.add(
+        yield* Database.add(
           Trigger.make({
             enabled: true,
-            spec: {
-              kind: 'queue',
-              queue: inboxQueue.dxn.toString(),
-            },
-            function: Ref.make(FunctionDefinition.serialize(agent)),
+            spec: Trigger.specQueue(inboxQueue.dxn.toString()),
+            function: Ref.make(Operation.serialize(AgentWorker)),
             input: {
-              initiative: Ref.make(initiative),
+              agent: Ref.make(agent),
               event: '{{event}}',
             },
           }),
@@ -111,25 +193,172 @@ describe('Initiative', () => {
         );
 
         const dispatcher = yield* TriggerDispatcher;
-        yield* dispatcher.invokeScheduledTriggers({ kinds: ['queue'], untilExhausted: true });
+        const invocations = yield* dispatcher.invokeScheduledTriggers({ kinds: ['queue'], untilExhausted: true });
+        expect(invocations.every((invocation) => Exit.isSuccess(invocation.result))).toBe(true);
+
+        console.log(yield* Effect.promise(() => dumpAgent(agent)));
+      },
+      WithProperties,
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+    MemoizedAiService.isGenerationEnabled() ? 240_000 : 30_000,
+  );
+
+  it.scoped(
+    'cron field creates a timer trigger that invokes the agent worker',
+    Effect.fnUntraced(
+      function* ({ expect }) {
+        const cron = '*/5 * * * *';
+        const agent = yield* Agent.makeInitialized(
+          {
+            name: 'Scheduled agent',
+            instructions: 'A scheduled agent that runs on a timer.',
+            blueprints: [Ref.make(MarkdownBlueprint.make())],
+            cron,
+          },
+          blueprint,
+        );
+        yield* Database.flush();
+
+        yield* Operation.invoke(SyncTriggers, { agent: Ref.make(agent) });
+
+        const triggers = yield* Database.runQuery(
+          Query.select(Filter.type(Trigger.Trigger)).debugLabel('assistant-toolkit.blueprint.test.timer'),
+        );
+        const timerTriggers = triggers.filter(
+          (trigger) => trigger.spec?.kind === 'timer' && trigger.spec.cron === cron,
+        );
+        expect(timerTriggers).toHaveLength(1);
+
+        const timerTrigger = timerTriggers[0];
+        invariant(timerTrigger.spec?.kind === 'timer');
+        expect(timerTrigger.spec.cron).toBe(cron);
+        expect(timerTrigger.enabled).toBe(true);
+
+        // Timer trigger bypasses the qualifier and points to the agent worker.
+        invariant(timerTrigger.function);
+        const operation = yield* Database.load(timerTrigger.function);
+        invariant(Obj.instanceOf(Operation.PersistentOperation, operation));
+        expect(operation.key).toBe(AgentWorker.meta.key);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
 
-        console.log(yield* Effect.promise(() => dumpInitiative(initiative)));
+  it.scoped(
+    'planning',
+    Effect.fnUntraced(
+      function* (_) {
+        const agent = yield* Agent.makeInitialized(
+          {
+            name: 'Egg making',
+            instructions: trim`
+              I'm testing how planning (task management) works.
+              Create tasks to make scrambled eggs.
+
+              Then simulate this plan execution in a markdown document.
+              The document should reflect the state of all objects involved in the cooking process.
+              The document should also have the log of actions taken.
+
+              Important: simualte actions one by one, in the order they are listed.
+              Simlate by updating the local document.
+
+              <example>
+                # State
+
+                - 2 raw eggs
+                - 1 frying pan
+                
+                # Action log
+                
+                - Taken 2 raw eggs out of the fridge.
+              </example>
+            `,
+            blueprints: [Ref.make(MarkdownBlueprint.make()), Ref.make(Obj.clone(PlanningBlueprint.make()))],
+          },
+          blueprint,
+        );
+        yield* Database.flush();
+
+        const chatFeed = agent.chat?.target?.feed?.target;
+        invariant(chatFeed, 'Agent chat feed not found.');
+        yield* Database.flush();
+        const runtime = yield* Effect.runtime<Feed.FeedService>();
+        const session = yield* acquireReleaseResource(() => new AiSession({ feed: chatFeed, runtime }));
+        yield* Effect.promise(() => session.context.open());
+
+        yield* session
+          .createRequest({
+            system: SYSTEM,
+            prompt: `Go`,
+          })
+          .pipe(Effect.provide(session.makeToolExecutionServices()));
+
+        console.log(yield* Effect.promise(() => dumpAgent(agent)));
       },
+      WithProperties,
       Effect.provide(TestLayer),
       TestHelpers.provideTestContext,
     ),
     MemoizedAiService.isGenerationEnabled() ? 240_000 : 30_000,
   );
+
+  it.scoped(
+    'sync-triggers sets trigger enabled from agent.enabled',
+    Effect.fnUntraced(
+      function* ({ expect }) {
+        const agent = yield* Agent.makeInitialized(
+          {
+            name: 'Toggle agent',
+            instructions: 'Test enabled propagation.',
+            blueprints: [Ref.make(MarkdownBlueprint.make())],
+            enabled: false,
+            cron: '0 9 * * *',
+          },
+          blueprint,
+        );
+        yield* Database.flush();
+
+        yield* Operation.invoke(SyncTriggers, { agent: Ref.make(agent) });
+
+        const triggers = yield* Database.runQuery(
+          Query.select(Filter.type(Trigger.Trigger)).debugLabel('assistant-toolkit.blueprint.test.toggle-enabled'),
+        );
+        expect(triggers.every((trigger) => trigger.enabled === false)).toBe(true);
+
+        Obj.update(agent, (agent) => {
+          agent.enabled = true;
+        });
+        yield* Database.flush();
+        yield* Operation.invoke(SyncTriggers, { agent: Ref.make(agent) });
+
+        const triggersAfter = yield* Database.runQuery(
+          Query.select(Filter.type(Trigger.Trigger)).debugLabel('assistant-toolkit.blueprint.test.after'),
+        );
+        expect(triggersAfter).toHaveLength(triggers.length);
+        expect(triggersAfter.every((trigger) => trigger.enabled === true)).toBe(true);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
 });
 
-const dumpInitiative = async (initiative: Initiative.Initiative) => {
+const dumpAgent = async (agent: Agent.Agent) => {
   let text = '';
-  text += `============== Initiative: ${initiative.name} ==============\n\n`;
-  for (const artifact of initiative.artifacts) {
+  text += `============== Agent: ${agent.name} ==============\n\n`;
+  text += `============== Instructions ==============\n\n`;
+  text += `${await agent.instructions.load().then((_) => _.content)}\n`;
+  text += `============== Plan ==============\n\n`;
+  text += `${await agent.plan?.load().then((_) => Plan.formatPlan(_))}\n`;
+  text += `============== Artifacts ==============\n\n`;
+  for (const artifact of agent.artifacts) {
     const data = await artifact.data.load();
     text += `============== ${artifact.name} (${Obj.getTypename(data)}) ==============\n`;
-    if (Obj.instanceOf(Text.Text, data)) {
-      text += `    ${data.content}\n`;
+    if (Obj.instanceOf(Markdown.Document, data)) {
+      text += `# ${Obj.getLabel(data)}\n\n${await data.content.load().then((_) => _.content)}\n`;
     } else {
       text += `    ${JSON.stringify(data, null, 2)}\n`;
     }

package/src/blueprints/project/blueprint.ts

@@ -0,0 +1,64 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Blueprint, Template } from '@dxos/compute';
+import { trim } from '@dxos/util';
+
+import { AddArtifact } from './functions';
+
+const BLUEPRINT_KEY = 'org.dxos.blueprint.agent';
+
+/**
+ * Creates the Agent blueprint. This is a function to avoid circular dependency issues.
+ */
+// TODO(dmaretskyi): Combine with Agent Wizard.
+const make = () =>
+  Blueprint.make({
+    key: BLUEPRINT_KEY,
+    name: 'Agent blueprint',
+    instructions: Template.make({
+      source: trim`
+        You work on an agent. Each agent has instructions - the goal of the agent.
+        The agent plan shows the current progress of the agent.
+        Agent has a 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 agent using the add-artifact function.
+
+        {{#with agent}}
+        <agent id="{{id}}" name="{{name}}">
+          <instructions>
+            {{instructions}}
+          </instructions>
+          <plan>
+            {{plan}}
+          </plan>
+
+          <artifacts>
+          {{#each artifacts}}
+            <artifact type="{{type}}" dxn="{{dxn}}">
+              {{name}}
+            </artifact>
+          {{/each}}
+          </artifacts>
+        </agent>
+        {{/with}}
+      `,
+      inputs: [
+        {
+          name: 'agent',
+          kind: 'function',
+          function: 'org.dxos.function.agent.get-context',
+        },
+      ],
+    }),
+    tools: Blueprint.toolDefinitions({ operations: [AddArtifact] }),
+  });
+
+const blueprint: Blueprint.Definition = {
+  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 { Operation } from '@dxos/compute';
+import { Database, Obj } from '@dxos/echo';
+
+import { Agent } 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 agent = yield* Agent.getFromChatContext;
+
+      Obj.update(agent, (agent) => {
+        agent.artifacts.push({
+          name,
+          data: artifact,
+        });
+      });
+    }) as any,
+  ),
+);

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

@@ -0,0 +1,69 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { AiService } from '@dxos/ai';
+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 { ContentBlock } from '@dxos/types';
+
+import { Agent } from '../../../types';
+import { AgentWorker } from './definitions';
+
+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 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({ feed: chatFeed, runtime }));
+
+      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.');
+      }
+
+      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* 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

@@ -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,
+  ],
+});
+
+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],
+});
+
+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],
+});
+
+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],
+});