@dxos/assistant-toolkit 0.8.4-main.69d29f4 → 0.8.4-main.6fa680abb7

package/src/{functions/tasks → blueprints/planning-old/functions}/read.ts

@@ -5,28 +5,27 @@
 import * as Effect from 'effect/Effect';
 import * as Schema from 'effect/Schema';
 
-import { ArtifactId } from '@dxos/assistant';
-import { Database } from '@dxos/echo';
+import { Database, Ref } from '@dxos/echo';
 import { defineFunction } from '@dxos/functions';
 import { Markdown } from '@dxos/plugin-markdown/types';
 
 export default defineFunction({
-  key: 'dxos.org/function/markdown/read-tasks',
+  key: 'org.dxos.function.markdown.read-tasks',
   name: 'Read',
   description: 'Read markdown tasks.',
   inputSchema: Schema.Struct({
-    id: ArtifactId.annotations({
+    doc: Ref.Ref(Markdown.Document).annotations({
       description: 'The ID of the document to read.',
     }),
   }),
   outputSchema: Schema.Struct({
     content: Schema.String,
   }),
-  handler: Effect.fn(function* ({ data: { id } }) {
-    const doc = yield* Database.Service.resolve(ArtifactId.toDXN(id), Markdown.Document);
+  handler: Effect.fn(function* ({ data: { doc } }) {
+    const document = yield* Database.load(doc);
 
     // Return content with line numbers prefixed.
-    const { content } = yield* Database.Service.load(doc.content);
+    const { content } = yield* Database.load(document.content);
     const lines = content.split('\n');
     const len = String(lines.length).length;
     const numbered = lines.map((line, i) => `${String(i + 1).padStart(len, ' ')}. ${line}`).join('\n');

package/src/{functions/tasks → blueprints/planning-old/functions}/update.ts

@@ -5,19 +5,18 @@
 import * as Effect from 'effect/Effect';
 import * as Schema from 'effect/Schema';
 
-import { ArtifactId } from '@dxos/assistant';
-import { Database } from '@dxos/echo';
+import { Database, Ref } from '@dxos/echo';
 import { defineFunction } from '@dxos/functions';
 import { Markdown } from '@dxos/plugin-markdown/types';
 
 import { MarkdownTasks, type TaskOperation } from './task-list';
 
 export default defineFunction({
-  key: 'dxos.org/function/markdown/update-tasks',
+  key: 'org.dxos.function.markdown.update-tasks',
   name: 'Update markdown',
   description: 'Creates and updates tasks in markdown documents.',
   inputSchema: Schema.Struct({
-    id: ArtifactId.annotations({
+    doc: Ref.Ref(Markdown.Document).annotations({
       description: 'The ID of the document to update.',
     }),
     operations: Schema.optional(
@@ -34,11 +33,11 @@ export default defineFunction({
       description: 'Content with line numbers for agent reference.',
     }),
   }),
-  handler: Effect.fn(function* ({ data: { id, operations = [] } }) {
-    const doc = yield* Database.Service.resolve(ArtifactId.toDXN(id), Markdown.Document);
+  handler: Effect.fn(function* ({ data: { doc, operations = [] } }) {
+    const document = yield* Database.load(doc);
 
     // Create task manager and apply operations if provided.
-    const { content } = yield* Database.Service.load(doc.content);
+    const { content } = yield* Database.load(document.content);
     const taskManager = new MarkdownTasks(content);
     if (operations.length > 0) {
       taskManager.applyOperations(operations as TaskOperation[]);

package/src/blueprints/planning-old/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { default as PlanningOldBlueprint } from './blueprint';

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

@@ -2,56 +2,83 @@
 // 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 { SpaceProperties } from '@dxos/client-protocol';
 import { Database, Obj, 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 { TriggerDispatcher } from '@dxos/functions-runtime';
 import { invariant } from '@dxos/invariant';
 import { ObjectId } from '@dxos/keys';
+import { MarkdownBlueprint } from '@dxos/plugin-markdown/blueprints';
+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, Project } from '../../types';
+import { PlanningBlueprint } from '../planning';
+
+import ProjectBlueprintDef from './blueprint';
+import { ProjectFunctions } from './functions';
 
 ObjectId.dangerouslyDisableRandomness();
 
 const TestLayer = AssistantTestLayerWithTriggers({
   aiServicePreset: 'edge-remote',
-  functions: [...Initiative.functions],
-  types: [Initiative.Initiative, Blueprint.Blueprint, Trigger.Trigger, Text.Text],
+  functions: [...Object.values(ProjectFunctions), ...MarkdownBlueprint.functions],
+  types: [
+    Project.Project,
+    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.runIf(TestHelpers.tagEnabled('flaky'))('Project', () => {
+  const blueprint = ProjectBlueprintDef.make();
   it.scoped(
     'shopping list',
     Effect.fnUntraced(
       function* (_) {
-        const initiative = yield* Database.Service.add(
-          yield* Initiative.make({
-            name: 'Shopping list',
-            spec: 'Keep a shopping list of items to buy.',
-          }),
-        );
-        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 }),
+        const project = yield* Database.add(
+          yield* Project.makeInitialized(
+            {
+              name: 'Shopping list',
+              spec: 'Keep a shopping list of items to buy.',
+              blueprints: [Ref.make(MarkdownBlueprint.make())],
+            },
+            blueprint,
+          ),
         );
+        const chatQueue = project.chat?.target?.queue?.target as any;
+        invariant(chatQueue, 'Project chat queue not found.');
+        yield* Database.flush({ indexes: true });
+        const conversation = yield* acquireReleaseResource(() => new AiConversation({ queue: chatQueue }));
         yield* Effect.promise(() => conversation.context.open());
 
         yield* conversation.createRequest({
@@ -59,7 +86,7 @@ describe('Initiative', () => {
           prompt: `List ingredients for a scrambled eggs on a toast breakfast.`,
         });
 
-        console.log(yield* Effect.promise(() => dumpInitiative(initiative)));
+        console.log(yield* Effect.promise(() => dumpProject(project)));
       },
       Effect.provide(TestLayer),
       TestHelpers.provideTestContext,
@@ -71,35 +98,38 @@ describe('Initiative', () => {
     'expense tracking list',
     Effect.fnUntraced(
       function* (_) {
-        const initiative = yield* Database.Service.add(
-          yield* Initiative.make({
-            name: 'Expense tracking',
-            spec: 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
-
-              - Flight to London (2026-02-01): £100
-              - Hotel in London (2026-02-01): £100
-            `,
-          }),
+        const project = yield* Database.add(
+          yield* Project.makeInitialized(
+            {
+              name: 'Expense tracking',
+              spec: trim`
+                Keep a list of expenses in a markdown document (create artifact "Expenses").
+                Process incoming emails, add the relevant ones to the list.
+
+                Format:
+
+                ## 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({ indexes: true });
 
         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)),
+            function: Ref.make(FunctionDefinition.serialize(ProjectFunctions.Agent)),
             input: {
-              initiative: Ref.make(initiative),
+              project: Ref.make(project),
               event: '{{event}}',
             },
           }),
@@ -111,10 +141,69 @@ 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(() => dumpProject(project)));
+      },
+      WithProperties,
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+    MemoizedAiService.isGenerationEnabled() ? 240_000 : 30_000,
+  );
+
+  it.scoped(
+    'planning',
+    Effect.fnUntraced(
+      function* (_) {
+        const project = yield* Database.add(
+          yield* Project.makeInitialized(
+            {
+              name: 'Egg making',
+              spec: 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({ indexes: true });
+
+        const chatQueue = project.chat?.target?.queue?.target as any;
+        invariant(chatQueue, 'Project chat queue not found.');
+        yield* Database.flush({ indexes: true });
+        const conversation = yield* acquireReleaseResource(() => new AiConversation({ queue: chatQueue }));
+        yield* Effect.promise(() => conversation.context.open());
+
+        yield* conversation.createRequest({
+          system: SYSTEM,
+          prompt: `Go`,
+        });
 
-        console.log(yield* Effect.promise(() => dumpInitiative(initiative)));
+        console.log(yield* Effect.promise(() => dumpProject(project)));
       },
+      WithProperties,
       Effect.provide(TestLayer),
       TestHelpers.provideTestContext,
     ),
@@ -122,14 +211,19 @@ describe('Initiative', () => {
   );
 });
 
-const dumpInitiative = async (initiative: Initiative.Initiative) => {
+const dumpProject = async (project: Project.Project) => {
   let text = '';
-  text += `============== Initiative: ${initiative.name} ==============\n\n`;
-  for (const artifact of initiative.artifacts) {
+  text += `============== Project: ${project.name} ==============\n\n`;
+  text += `============== Spec ==============\n\n`;
+  text += `${await project.spec.load().then((_) => _.content)}\n`;
+  text += `============== Plan ==============\n\n`;
+  text += `${await project.plan?.load().then((_) => Plan.formatPlan(_))}\n`;
+  text += `============== Artifacts ==============\n\n`;
+  for (const artifact of project.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,68 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type AppCapabilities } from '@dxos/app-toolkit';
+import { Blueprint, Template } from '@dxos/blueprints';
+import { trim } from '@dxos/util';
+
+import { ProjectFunctions } from './functions';
+
+const BLUEPRINT_KEY = 'org.dxos.blueprint.project';
+
+const functions = [ProjectFunctions.AddArtifact];
+
+/**
+ * Creates the Project blueprint. This is a function to avoid circular dependency issues.
+ */
+const make = () =>
+  Blueprint.make({
+    key: BLUEPRINT_KEY,
+    name: 'Project blueprint',
+    instructions: Template.make({
+      source: trim`
+        You work on an project. Each project has a spec - the goal of the project.
+        The project plan shows the current progress of the project.
+        Project has an number of associated artifacts you can read/write.
+        Spec and plan are also artifacts.
+        You can edit them if necessary.
+
+        IMPORTANT: When create a new artifact, always add it to the project using the add-artifact function.
+
+        {{#with project}}
+        <project id="{{id}}" name="{{name}}">
+          <spec>
+            {{spec}}
+          </spec>
+          <plan>
+            {{plan}}
+          </plan>
+
+          <artifacts>
+          {{#each artifacts}}
+            <artifact type="{{type}}" dxn="{{dxn}}">
+              {{name}}
+            </artifact>
+          {{/each}}
+          </artifacts>
+        </project>
+        {{/with}}
+      `,
+      inputs: [
+        {
+          name: 'project',
+          kind: 'function',
+          function: 'org.dxos.function.project.get-context',
+        },
+      ],
+    }),
+    tools: Blueprint.toolDefinitions({ functions }),
+  });
+
+const blueprint: AppCapabilities.BlueprintDefinition = {
+  key: BLUEPRINT_KEY,
+  functions,
+  make,
+};
+
+export default blueprint;

package/src/blueprints/project/functions/add-artifact.ts

@@ -0,0 +1,41 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { AiContextService } from '@dxos/assistant';
+import { Database, Obj, Ref } from '@dxos/echo';
+import { defineFunction } from '@dxos/functions';
+
+import { Project } from '../../../types';
+
+export default defineFunction({
+  key: 'org.dxos.function.project.add-artifact',
+  name: 'Add artifact',
+  description: 'Adds a new artifact.',
+  inputSchema: 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.',
+    }),
+  }),
+  services: [AiContextService],
+  handler: Effect.fnUntraced(function* ({ data }) {
+    if (!(yield* Database.load(data.artifact))) {
+      throw new Error('Artifact not found.');
+    }
+
+    const project = yield* Project.getFromChatContext;
+
+    Obj.change(project, (project) => {
+      project.artifacts.push({
+        name: data.name,
+        data: data.artifact,
+      });
+    });
+  }, AiContextService.fixFunctionHandlerType),
+});

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

@@ -0,0 +1,72 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+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 { acquireReleaseResource } from '@dxos/effect';
+import { TriggerEvent, defineFunction } from '@dxos/functions';
+import { invariant } from '@dxos/invariant';
+import { type Message } from '@dxos/types';
+
+import { Project } from '../../../types';
+
+export default defineFunction({
+  key: 'org.dxos.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.');
+
+      const chatQueue = yield* project.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> }),
+      );
+
+      const iniativesInContext = conversation.context.getObjects().filter(Obj.instanceOf(Project.Project));
+      if (iniativesInContext.length !== 1) {
+        throw new Error('There should be exactly one project in context. Got: ' + iniativesInContext.length);
+      }
+
+      if (!data.prompt && !data.event) {
+        throw new Error('Either prompt or event must be provided.');
+      }
+
+      let input = '';
+      if (data.prompt) {
+        input += `${data.prompt}\n\n`;
+      }
+      if (data.event) {
+        input += `<event>\n${JSON.stringify(data.event, null, 2)}\n</event>\n\n`;
+      }
+
+      yield* conversation
+        .createRequest({
+          prompt: input,
+        })
+        .pipe(Effect.retry({ times: 2 }));
+    },
+    Effect.scoped,
+    Effect.provide(AiService.model('@anthropic/claude-sonnet-4-5')),
+    AiContextService.fixFunctionHandlerType,
+  ) as any,
+});

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

@@ -0,0 +1,63 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { AiContextService } from '@dxos/assistant';
+import { Database, Obj } from '@dxos/echo';
+import { defineFunction } from '@dxos/functions';
+
+import { Plan, Project } from '../../../types';
+
+export default defineFunction({
+  key: 'org.dxos.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;
+
+    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),
+});

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

@@ -0,0 +1,15 @@
+//
+// 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';
+
+export const ProjectFunctions = {
+  AddArtifact,
+  Agent,
+  GetContext,
+  Qualifier,
+};