@dxos/assistant-toolkit 0.8.4-main.ae835ea → 0.8.4-main.bc2380dfbc

package/src/blueprints/memory/blueprint.test.ts

@@ -0,0 +1,139 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { OpaqueToolkit } from '@dxos/ai';
+import { Blueprint } from '@dxos/compute';
+import { Database, Feed, Filter, Obj, Query } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { AgentService } from '@dxos/functions-runtime';
+import { AssistantTestLayer } from '@dxos/functions-runtime/testing';
+import { ObjectId } from '@dxos/keys';
+
+import { Memory } from '../../types/Memory';
+import { WebSearchBlueprint, WebSearchToolkit } from '../websearch';
+import MemoryBlueprint from './blueprint';
+import { MemoryHandlers } from './functions';
+
+ObjectId.dangerouslyDisableRandomness();
+
+const TestLayer = AssistantTestLayer({
+  aiServicePreset: 'edge-remote',
+  operationHandlers: MemoryHandlers,
+  types: [Memory, Blueprint.Blueprint, Feed.Feed],
+  blueprints: [MemoryBlueprint.make()],
+  tracing: 'pretty',
+});
+
+const TestLayerWithWebSearch = AssistantTestLayer({
+  aiServicePreset: 'edge-remote',
+  operationHandlers: MemoryHandlers,
+  toolkits: [OpaqueToolkit.make(WebSearchToolkit, Layer.empty)],
+  types: [Memory, Blueprint.Blueprint, Feed.Feed],
+  blueprints: [MemoryBlueprint.make(), WebSearchBlueprint.make()],
+  tracing: 'pretty',
+});
+
+describe('Memory Blueprint', () => {
+  it.effect(
+    'save: saves a memory',
+    Effect.fnUntraced(
+      function* (_) {
+        const agent = yield* AgentService.createSession({
+          blueprints: [MemoryBlueprint.make()],
+        });
+        yield* agent.submitPrompt('Remember that my favorite programming language is TypeScript.');
+        yield* agent.waitForCompletion();
+        const memories = yield* Database.runQuery(Query.select(Filter.type(Memory)));
+        expect(memories.length).toBeGreaterThanOrEqual(1);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 60_000 },
+  );
+
+  it.effect(
+    'query: searches memories by text',
+    Effect.fnUntraced(
+      function* (_) {
+        yield* Database.add(
+          Obj.make(Memory, {
+            title: 'Favorite color',
+            content: 'The user prefers blue.',
+          }),
+        );
+        yield* Database.add(
+          Obj.make(Memory, {
+            title: 'Meeting notes',
+            content: 'Discussed project timeline with Alice.',
+          }),
+        );
+        const agent = yield* AgentService.createSession({
+          blueprints: [MemoryBlueprint.make()],
+        });
+        yield* agent.submitPrompt('Search your memories for anything about colors.');
+        yield* agent.waitForCompletion();
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 60_000 },
+  );
+
+  it.effect(
+    'delete: removes a memory',
+    Effect.fnUntraced(
+      function* (_) {
+        yield* Database.add(
+          Obj.make(Memory, {
+            title: 'Outdated fact',
+            content: 'The sky is green.',
+          }),
+        );
+        const agent = yield* AgentService.createSession({
+          blueprints: [MemoryBlueprint.make()],
+        });
+        yield* agent.submitPrompt('Delete the memory about "Outdated fact".');
+        yield* agent.waitForCompletion();
+        const memories = yield* Database.runQuery(Query.select(Filter.type(Memory)));
+        const found = memories.find((memory) => memory.title === 'Outdated fact');
+        expect(found).toBeUndefined();
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 60_000 },
+  );
+
+  it.effect(
+    'natural: saves memories from a conversation with web search',
+    Effect.fnUntraced(
+      function* (_) {
+        const agent = yield* AgentService.createSession({
+          blueprints: [MemoryBlueprint.make(), WebSearchBlueprint.make()],
+        });
+        yield* agent.submitPrompt(
+          "I'm going to LA next week. Find me some good hotels and remember the recommendations.",
+        );
+        yield* agent.waitForCompletion();
+        const memories = yield* Database.runQuery(Query.select(Filter.type(Memory)));
+        expect(memories.length).toBeGreaterThanOrEqual(1);
+        const hasLAMemory = memories.some(
+          (memory) =>
+            memory.title.toLowerCase().includes('la') ||
+            memory.title.toLowerCase().includes('los angeles') ||
+            memory.content.toLowerCase().includes('hotel'),
+        );
+        expect(hasLAMemory).toBe(true);
+      },
+      Effect.provide(TestLayerWithWebSearch),
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 120_000 },
+  );
+});

package/src/blueprints/memory/blueprint.ts

@@ -0,0 +1,41 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Blueprint } from '@dxos/compute';
+import { Ref } from '@dxos/echo';
+import { Text } from '@dxos/schema';
+import { trim } from '@dxos/util';
+
+import { QueryMemories, SaveMemory, DeleteMemory } from './functions';
+
+const BLUEPRINT_KEY = 'org.dxos.blueprint.memory';
+
+const instructions = trim`
+  You have the ability to save and recall memories.
+  Memories are persistent knowledge units stored in the database.
+  Use memories to remember facts, user preferences, decisions, and any knowledge that should persist across conversations.
+
+  When the user asks you to remember something, save it as a memory with a descriptive title.
+  When the user asks about something you might have stored, query your memories first.
+  You can also delete outdated or incorrect memories.
+`;
+
+const make = () =>
+  Blueprint.make({
+    key: BLUEPRINT_KEY,
+    name: 'Memory',
+    description: 'Persistent memory storage and retrieval.',
+    agentCanEnable: true,
+    instructions: {
+      source: Ref.make(Text.make({ content: instructions })),
+    },
+    tools: Blueprint.toolDefinitions({ operations: [SaveMemory, QueryMemories, DeleteMemory] }),
+  });
+
+const blueprint: Blueprint.Definition = {
+  key: BLUEPRINT_KEY,
+  make,
+};
+
+export default blueprint;

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

@@ -0,0 +1,68 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Operation } from '@dxos/compute';
+import { Database, Ref } from '@dxos/echo';
+
+import { Memory } from '../../../types/Memory';
+
+export const QueryMemories = Operation.make({
+  meta: {
+    key: 'org.dxos.function.memory.query',
+    name: 'Query memories',
+    description:
+      'Search for stored memories using full-text search. Returns memories matching the query terms. Use this to recall previously saved knowledge, facts, or preferences.',
+  },
+  input: Schema.Struct({
+    text: Schema.optional(
+      Schema.String.annotations({
+        description: 'Full-text search query. Omit to list all memories.',
+        examples: ['new york trip date plan', 'favorite color', 'project cyberdyne'],
+      }),
+    ),
+    limit: Schema.optional(
+      Schema.Number.annotations({
+        description: 'Maximum number of results to return.',
+        default: 10,
+      }),
+    ),
+  }),
+  output: Schema.Array(Schema.Unknown),
+  services: [Database.Service],
+});
+
+export const SaveMemory = Operation.make({
+  meta: {
+    key: 'org.dxos.function.memory.save',
+    name: 'Save memory',
+    description:
+      'Saves a new memory to the database. Use this to persist knowledge, facts, preferences, or any information that should be remembered across conversations.',
+  },
+  input: Schema.Struct({
+    title: Schema.String.annotations({
+      description: 'Short descriptive title for the memory.',
+    }),
+    content: Schema.String.annotations({
+      description:
+        'The content of the memory. Can be a fact, preference, instruction, or any knowledge worth persisting.',
+    }),
+  }),
+  output: Schema.Unknown,
+  services: [Database.Service],
+});
+
+export const DeleteMemory = Operation.make({
+  meta: {
+    key: 'org.dxos.function.memory.delete',
+    name: 'Delete memory',
+    description: 'Deletes a memory from the database. Use this to remove outdated or incorrect memories.',
+  },
+  input: Schema.Struct({
+    memory: Ref.Ref(Memory),
+  }),
+  output: Schema.Void,
+  services: [Database.Service],
+});

package/src/blueprints/memory/functions/delete.ts

@@ -0,0 +1,20 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/compute';
+import { Database } from '@dxos/echo';
+
+import { DeleteMemory } from './definitions';
+
+export default DeleteMemory.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ memory }) {
+      const memoryObj = yield* Database.load(memory);
+      yield* Database.remove(memoryObj);
+      yield* Database.flush();
+    }),
+  ),
+);

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

@@ -0,0 +1,13 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/compute';
+
+export * from './definitions';
+
+export const MemoryHandlers = OperationHandlerSet.lazy(
+  () => import('./save'),
+  () => import('./query'),
+  () => import('./delete'),
+);

package/src/blueprints/memory/functions/query.ts

@@ -0,0 +1,32 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/compute';
+import { Database, Entity, Filter, Query } from '@dxos/echo';
+
+import { Memory } from '../../../types/Memory';
+import { QueryMemories } from './definitions';
+
+export default QueryMemories.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ text, limit = 10 }) {
+      let query: Query.Any;
+      if (text) {
+        query = Query.all(
+          // TODO(dmaretskyi): We should move this to the query executor layer.
+          ...text.split(' ').map((term) => Query.select(Filter.text(term, { type: 'full-text' }))),
+        ).select(Filter.type(Memory));
+      } else {
+        query = Query.select(Filter.type(Memory));
+      }
+      query = query.limit(limit);
+
+      yield* Database.flush();
+      const results = yield* Database.runQuery(query);
+      return results.map((obj) => Entity.toJSON(obj));
+    }),
+  ),
+);

package/src/blueprints/memory/functions/save.ts

@@ -0,0 +1,20 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/compute';
+import { Database, Entity, Obj } from '@dxos/echo';
+
+import { Memory } from '../../../types/Memory';
+import { SaveMemory } from './definitions';
+
+export default SaveMemory.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ title, content }) {
+      const memory = yield* Database.add(Obj.make(Memory, { title, content }));
+      return Entity.toJSON(memory);
+    }),
+  ),
+);

package/src/blueprints/memory/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { default as MemoryBlueprint } from './blueprint';
+export { QueryMemories, SaveMemory, DeleteMemory, MemoryHandlers } from './functions';

package/src/blueprints/planning/blueprint.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Blueprint } from '@dxos/compute';
+
+import { UpdateTasks } from './functions';
+
+const BLUEPRINT_KEY = 'org.dxos.blueprint.planning';
+
+const make = () =>
+  Blueprint.make({
+    key: BLUEPRINT_KEY,
+    name: 'Planning',
+    description: 'Plans and tracks complex tasks using artifacts.',
+    tools: Blueprint.toolDefinitions({ operations: [UpdateTasks] }),
+  });
+
+const blueprint: Blueprint.Definition = {
+  key: BLUEPRINT_KEY,
+  make,
+};
+
+export default blueprint;

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

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/compute';
+
+export * from './update-tasks';
+
+export const PlanningHandlers = OperationHandlerSet.lazy(() => import('./update-tasks'));

package/src/blueprints/planning/functions/update-tasks.md

@@ -0,0 +1,116 @@
+## PLANNING TOOL
+
+This tool maintains an organized task list.
+Use this to track progress, break down objectives, and ensure thoroughness.
+If you are asked to create a plan use this tool instead of creating a new document.
+After creating initial tasks, update them silently without announcing changes to the user.
+Important: Do not show or summarize the contents of the task list unless the user asks for this.
+
+### CORE USAGE PRINCIPLES
+
+Create and manage tasks for: multi-step objectives requiring 3+ distinct actions, complex projects needing careful sequencing,
+user requests for task organization, multiple deliverables provided together, new instructions (capture as tasks immediately with new IDs),
+completed work (mark `done` and add follow-ups), and active work (mark as `in-progress`, limit one at a time).
+
+Skip task management for: single straightforward actions, simple requests achievable in 1-2 steps,
+informational queries, quick lookups or clarifications, and avoid creating verification tasks unless requested.
+
+### TOOL SPECIFICATION
+
+`update-tasks` requires an array of task objects. Each task object contains:
+
+- id (string, required): unique identifier like "task_1" or "research_sources"
+- title (string, optional): update to clarify or refine task description
+- status (string, optional): `todo` | `in-progress` | `done`
+
+Task status meanings: 'todo' means not yet started, `in-progress` means currently being worked on, `done` means completed successfully.
+
+### OPERATIONAL GUIDELINES
+
+Update tasks in realtime as work progresses. Mark tasks `done` immediately upon completion.
+Maintain only ONE task with `in-progress` status at a time. Complete current tasks before starting new ones.
+Use specific, actionable task titles. Break complex work into manageable logical pieces.
+Batch task updates with other actions when possible for efficiency.
+
+### USAGE EXAMPLES
+
+<example type="research_project">
+<user_message>I need to research sustainable packaging options and write a report comparing costs and environmental impact.</user_message>
+<assistant_action>
+Creates tasks:
+1. {id: "research_materials", title: "Research sustainable packaging materials", status: "in-progress"}
+2. {id: "compare_costs", title: "Compile cost comparison data", status: "todo"}
+3. {id: "assess_impact", title: "Evaluate environmental impact metrics", status: "todo"}
+4. {id: "draft_report", title: "Write comparative analysis report", status: "todo"}
+
+Begins research work immediately in same response.
+</assistant_action>
+<reasoning>Multi-phase project requiring systematic tracking across research, analysis, and writing stages.</reasoning>
+</example>
+
+<example type="event_planning">
+<user_message>Help me plan a team retreat - venue, agenda, catering, and send invitations.</user_message>
+<assistant_action>
+Creates tasks:
+1. {id: "venue_options", title: "Research and recommend venues", status: "in-progress"}
+2. {id: "draft_agenda", title: "Create retreat agenda", status: "todo"}
+3. {id: "arrange_catering", title: "Coordinate catering options", status: "todo"}
+4. {id: "send_invites", title: "Draft and send invitations", status: "todo"}
+</assistant_action>
+<reasoning>Multiple distinct deliverables with dependencies requiring organized tracking.</reasoning>
+</example>
+
+<example type="document_analysis">
+<user_message>Review this 30-page contract for key terms, risks, and negotiation points.</user_message>
+<assistant_action>
+Creates tasks:
+1. {id: "extract_key_terms", title: "Identify key contractual terms", status: "in-progress"}
+2. {id: "flag_risks", title: "Flag potential risks and liabilities", status: "todo"}
+3. {id: "negotiation_points", title: "Compile negotiation recommendations", status: "todo"}
+4. {id: "summary_doc", title: "Prepare executive summary", status: "todo"}
+</assistant_action>
+<reasoning>Substantial analysis work requiring methodical breakdown and systematic review.</reasoning>
+</example>
+
+<example type="multiple_deliverables">
+<user_message>I need: 1) competitor analysis for three companies, 2) SWOT analysis, 3) market positioning recommendations.</user_message>
+<assistant_action>
+Creates tasks:
+1. {id: "competitor_research", title: "Research three competitor companies", status: "in-progress"}
+2. {id: "swot_analysis", title: "Develop SWOT analysis", status: "todo"}
+3. {id: "positioning_recs", title: "Create market positioning recommendations", status: "todo"}
+</assistant_action>
+<reasoning>User provided numbered list of distinct deliverables requiring separate effort.</reasoning>
+</example>
+
+<example type="skip_simple_question">
+<user_message>What's the difference between renewable and sustainable energy?</user_message>
+<assistant_action>Provides explanation directly without creating tasks.</assistant_action>
+<reasoning>Informational request with no actionable work to complete or track.</reasoning>
+</example>
+
+<example type="skip_quick_lookup">
+<user_message>Find the population of Tokyo.</user_message>
+<assistant_action>Searches and provides answer without task tracking.</assistant_action>
+<reasoning>Single straightforward lookup completable immediately.</reasoning>
+</example>
+
+<example type="skip_trivial_task">
+<user_message>Summarize this 2-paragraph email.</user_message>
+<assistant_action>Provides summary directly without creating tasks.</assistant_action>
+<reasoning>Single simple action requiring no breakdown or progress tracking.</reasoning>
+</example>
+
+<example type="skip_single_action">
+<user_message>Check if my flight is on time.</user_message>
+<assistant_action>Performs lookup and reports status without task management.</assistant_action>
+<reasoning>One-step action with immediate completion, no organizational benefit from tasks.</reasoning>
+</example>
+
+### BEST PRACTICES
+
+For task creation: use descriptive unique IDs reflecting the work, start first task as `in-progress`, batch initial creation with beginning work.
+For progress tracking: update status immediately upon completion, keep only one `in-progress` task unless parallel work is natural, add follow-up tasks as they emerge. For task breakdown: aim for reasonably-scoped tasks, group related small actions into logical units, split tasks requiring different approaches.
+
+When uncertain whether to use task management, err on the side of creating tasks.
+Proactive organization demonstrates thoroughness and ensures comprehensive work completion.

package/src/blueprints/planning/functions/update-tasks.test.ts

@@ -0,0 +1,55 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { Blueprint, Operation } from '@dxos/compute';
+import { Database, Feed, Obj } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { AssistantTestLayer } from '@dxos/functions-runtime/testing';
+import { invariant } from '@dxos/invariant';
+import { ObjectId } from '@dxos/keys';
+
+import { Agent, Chat, Plan } from '../../../types';
+import PlanningBlueprint from '../blueprint';
+import { PlanningHandlers } from './index';
+import { UpdateTasks } from './update-tasks';
+
+ObjectId.dangerouslyDisableRandomness();
+
+const TestLayer = AssistantTestLayer({
+  operationHandlers: PlanningHandlers,
+  types: [Agent.Agent, Plan.Plan, Chat.Chat, Chat.CompanionTo, Blueprint.Blueprint, Feed.Feed],
+  blueprints: [PlanningBlueprint.make()],
+  disableLlmMemoization: true,
+});
+
+describe('UpdateTasks', () => {
+  it.scoped(
+    'adds tasks to the plan',
+    Effect.fnUntraced(
+      function* ({ expect }) {
+        const agent = yield* Agent.makeInitialized(
+          { name: 'Planner', instructions: 'Test.' },
+          PlanningBlueprint.make(),
+        );
+        yield* Database.flush();
+
+        const chatFeed = agent.chat?.target?.feed?.target;
+        invariant(chatFeed, 'Agent chat feed not found.');
+
+        yield* Operation.invoke(UpdateTasks, {
+          tasks: [{ id: Plan.TaskId.make('task-1'), title: 'Hello', status: 'todo' }],
+        }).pipe(Effect.provide(Operation.withInvocationOptions({ conversation: Obj.getDXN(chatFeed).toString() })));
+
+        const plan = yield* Database.load(agent.plan);
+        expect(plan.tasks).toHaveLength(1);
+        expect(plan.tasks[0]).toMatchObject({ id: 'task-1', title: 'Hello', status: 'todo' });
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});

package/src/blueprints/planning/functions/update-tasks.ts

@@ -0,0 +1,67 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { AiContext } from '@dxos/assistant';
+import { Operation } from '@dxos/compute';
+import { Database, Obj } from '@dxos/echo';
+import { trim } from '@dxos/util';
+
+import { Plan, Agent } from '../../../types';
+import INSTRUCTIONS from './update-tasks.md?raw';
+
+const SimpleTask = Plan.Task.omit('chat');
+
+export const UpdateTasks = Operation.make({
+  meta: {
+    key: 'org.dxos.function.planning.update-tasks', // TODO(burdon): Are hyphens allowed?
+    name: 'Update tasks',
+    description: INSTRUCTIONS,
+  },
+  input: Schema.Struct({
+    tasks: Schema.Array(SimpleTask),
+  }),
+  output: Schema.Any,
+  services: [AiContext.Service, Database.Service],
+});
+
+/**
+ * Updates the planning document (Agent.plan) with the given tasks.
+ */
+export default UpdateTasks.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ tasks: newTasks }) {
+      const agent = yield* Agent.getFromChatContext;
+      // TODO(burdon): How to specify requirements/preconditions before calling?
+      // TODO(burdon): How to report non-technical error?
+      const plan = yield* Database.load(agent.plan);
+
+      Obj.update(plan, (plan) => {
+        for (const task of newTasks) {
+          const existingTask = plan.tasks.find((t) => t.id === task.id);
+          if (existingTask) {
+            existingTask.title = task.title;
+            existingTask.status = task.status;
+          } else {
+            plan.tasks.push({
+              id: task.id,
+              title: task.title,
+              status: task.status,
+            });
+          }
+        }
+      });
+
+      return trim`
+        You must update the task status to 'in-progress' when you start and 'done' when complete.
+        Current plan updated:
+        <plan>
+          ${Plan.formatPlan(plan)}
+        </plan>
+      `;
+    }) as any,
+  ),
+);

package/src/blueprints/planning/index.ts

@@ -1,7 +1,6 @@
 //
-// Copyright 2025 DXOS.org
+// Copyright 2026 DXOS.org
 //
 
-import blueprint from './planning-blueprint';
-
-export default blueprint;
+export { default as PlanningBlueprint } from './blueprint';
+export { UpdateTasks as PlanningUpdateTasks, PlanningHandlers } from './functions';