@dxos/assistant-toolkit 0.8.4-main.3eb6e50203 → 0.8.4-main.3fbcb4aa9b

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

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

@@ -0,0 +1,14 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/compute';
+
+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

@@ -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 { Operation } from '@dxos/compute';
+import { Database, Obj, Ref } from '@dxos/echo';
+import { invariant } from '@dxos/invariant';
+import { trim } from '@dxos/util';
+
+import { Plan, Agent } from '../../../types';
+import { Qualifier } from './definitions';
+
+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 } = agent;
+        if (!queue) {
+          throw new Error('Agent has no queue.');
+        }
+
+        const plan = yield* Database.load(agent.plan);
+        const instructions = yield* Database.load(agent.instructions);
+
+        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 event && event.item) {
+            const obj = event.item;
+            yield* Effect.promise(() => queueTarget.append([obj]));
+          } else if ('subject' in event && Ref.isRef(event.subject)) {
+            const obj = yield* Database.load(event.subject);
+            yield* Effect.promise(() => queueTarget.append([obj]));
+          } else {
+            throw new Error('Invalid event.');
+          }
+        }
+      },
+      Effect.provide(AiService.model('@anthropic/claude-sonnet-4-5')),
+    ),
+  ),
+);

package/src/blueprints/project/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { default as 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'),
+);

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

@@ -0,0 +1,77 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/compute';
+import { trim } from '@dxos/util';
+
+import { AgentRules } from './definitions';
+
+export default AgentRules.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* () {
+      return trim`
+        You can ask the user for qualifying questions about the agents.
+        If agents should actively read incoming emails, query for mailboxes and add a subscription to them.
+        If the user wants the agent to run on a schedule (e.g. "every morning", "every 5 minutes"), set the agent's \`cron\` field to a standard cron expression (e.g. \`0 9 * * *\` for daily at 09:00, \`*/5 * * * *\` for every 5 minutes). Timer triggers bypass the qualifier and invoke the agent worker directly on the schedule.
+        Use [query-blueprints] from the Blueprint Manager to query for available blueprints and their keys.
+        Use [create-agent] function to create a new agent.
+
+        Notable blueprints (query to get their keys):
+
+        - Blueprint Manger - allows agent to self-enable blueprints (always include this one).
+        - Database -- CRUD on objects in the ECHO database.
+        - Markdown -- Create and edit markdown documents.
+        - Websearch -- Search the web for information.
+        - Browser -- Virtual browser via playwright when simple WebSearch is not enough.
+        - Memory -- Memory to store and retrieve information.
+
+        Experimental blueprints that are discouraged:
+
+        - Research
+        - Design
+        - Agent (not wizard) -- those are agent internals, they are auto-added to every new agent.
+
+        <example_agent>
+          ## CRM from your inbox
+
+          Blueprints: database, websearch, browser
+
+          Subscribe to your inboxes.
+          Spec says that on every email we should extract People and Organizations and save them to the database, but first query the database for existing people and organizations to avoid duplicates.
+          Also run a quick research on the web to find more information about the person or organization and save it to the database.
+        </example_agent>
+
+        <example_agent>
+          ## Parcel tracking
+
+          Blueprints: database
+
+          Based on emails from vendors (amazon, fedex, etc.) track the status of the parcels ordered online and keep a table of orders.
+
+          Before creating an agent, use the Database blueprint to create an Order schema:
+            - seller
+            - name
+            - price
+            - status (enum of: pending, shipped, waiting for pickup, delivered, cancelled, returned)
+            - tracking numbers/notes
+            - date of delivery
+            - shipping address
+        </example_agent>
+
+        <example_agent>
+          ## Comms assistant
+
+          Blueprints: database, markdown, inbox
+
+          Helps user maintain comms with external parites via email.
+          Ask user specifically who they want to communicate with and on what topic.
+          Agent should keep a markdown document in artifacts outlining the current state of the comms.
+          Agent should propose drafts to follow up on the comms. Only propose sensible drafts, do not propose drafts that are not relevant or actionable.
+        </example_agent>
+      `;
+    }),
+  ),
+);

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

@@ -0,0 +1,158 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+import { Trigger, Operation } from '@dxos/compute';
+import { Database, Feed, Filter, Obj, Ref } from '@dxos/echo';
+import { FeedAnnotation } from '@dxos/schema';
+
+import { Agent } from '../../../types';
+import { SyncTriggers } from './definitions';
+
+export default SyncTriggers.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ agent: agentRef }) {
+      const agent = yield* Database.load(agentRef);
+      yield* syncAgentTriggers(agent);
+    }),
+  ),
+);
+
+/**
+ * Foreign key {@link AGENT_TRIGGER_EXTENSION_KEY} => <agent id : ObjectId>.
+ */
+const AGENT_TRIGGER_EXTENSION_KEY = 'org.dxos.extension.AgentTrigger';
+
+/**
+ * Foreign key {@link AGENT_TRIGGER_TARGET_EXTENSION_KEY} => <dxn string of subscription target>.
+ */
+const AGENT_TRIGGER_TARGET_EXTENSION_KEY = 'org.dxos.extension.AgentTriggerTarget';
+
+/** 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 agent subscriptions.
+ */
+const syncAgentTriggers = (agent: Agent.Agent): Effect.Effect<void, never, Database.Service> =>
+  Effect.gen(function* () {
+    const triggers = yield* Database.runQuery(
+      Filter.foreignKeys(Trigger.Trigger, [{ source: AGENT_TRIGGER_EXTENSION_KEY, id: agent.id }]),
+    );
+
+    // Remove all existing triggers — they will be recreated with the current config.
+    // This ensures operation, concurrency, and enabled stay in sync when agent fields change.
+    for (const trigger of triggers) {
+      yield* Database.remove(trigger);
+    }
+
+    const triggersEnabled = agent.enabled ?? true;
+
+    // Lazy import to avoid circular dependency issues.
+    const { Qualifier, AgentWorker } = yield* Effect.promise(() => import('../../project'));
+
+    for (const subscription of agent.subscriptions) {
+      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;
+      }
+
+      const filterEvents = agent.filterEvents ?? true;
+
+      yield* Database.add(
+        Trigger.make({
+          [Obj.Parent]: agent,
+          [Obj.Meta]: {
+            keys: [
+              { source: AGENT_TRIGGER_EXTENSION_KEY, id: agent.id },
+              { source: AGENT_TRIGGER_TARGET_EXTENSION_KEY, id: subscription.dxn.toString() },
+            ],
+          },
+          enabled: triggersEnabled,
+          spec: Trigger.specQueue(queueDxn.toString()),
+          function: Ref.make(Operation.serialize(filterEvents ? Qualifier : AgentWorker)),
+          input: {
+            agent: Ref.make(agent),
+            event: '{{event}}',
+          },
+          concurrency: filterEvents ? 5 : undefined,
+        }),
+      );
+    }
+
+    if ((agent.filterEvents ?? true) && agent.queue) {
+      yield* Database.add(
+        Trigger.make({
+          [Obj.Parent]: agent,
+          [Obj.Meta]: {
+            keys: [
+              { source: AGENT_TRIGGER_EXTENSION_KEY, id: agent.id },
+              {
+                source: AGENT_TRIGGER_TARGET_EXTENSION_KEY,
+                id: Obj.getDXN(agent)?.toString() ?? '',
+              },
+            ],
+          },
+          function: Ref.make(Operation.serialize(AgentWorker)),
+          enabled: triggersEnabled,
+          spec: Trigger.specQueue(agent.queue.dxn.toString()),
+          input: {
+            agent: Ref.make(agent),
+            event: '{{event}}',
+          },
+        }),
+      );
+    }
+
+    // Timer trigger bypasses the qualifier and invokes the agent worker directly on a schedule.
+    if (agent.cron) {
+      yield* Database.add(
+        Trigger.make({
+          [Obj.Parent]: agent,
+          [Obj.Meta]: {
+            keys: [
+              { source: AGENT_TRIGGER_EXTENSION_KEY, id: agent.id },
+              { source: AGENT_TRIGGER_TARGET_EXTENSION_KEY, id: `timer:${agent.cron}` },
+            ],
+          },
+          enabled: triggersEnabled,
+          spec: Trigger.specTimer(agent.cron),
+          function: Ref.make(Operation.serialize(AgentWorker)),
+          input: {
+            agent: Ref.make(agent),
+            event: '{{event}}',
+          },
+        }),
+      );
+    }
+
+    yield* Database.flush();
+  });

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

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { default as AgentWizardBlueprint } from './blueprint';
+export { AgentRules, CreateAgent, SyncTriggers, AgentWizardHandlers } from './functions';