@dxos/assistant-toolkit 0.8.4-main.1068cf700f

package/src/initiative/util.ts

@@ -0,0 +1,137 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Function from 'effect/Function';
+
+import { AiContextBinder, AiContextService, type ContextBinding } from '@dxos/assistant';
+import { type Blueprint } from '@dxos/blueprints';
+import { Database, Obj, Ref, Relation } from '@dxos/echo';
+import { type ObjectNotFoundError } from '@dxos/echo/Err';
+import { acquireReleaseResource } from '@dxos/effect';
+import { QueueService } from '@dxos/functions';
+import { invariant } from '@dxos/invariant';
+import { Text } from '@dxos/schema';
+import type { Message } from '@dxos/types';
+
+import * as Chat from '../chat/Chat';
+
+import { Initiative } from './Initiative';
+import { makePlan } from './plan';
+
+/**
+ * Creates a fully initialized Initiative with chat, queue, and context bindings.
+ *
+ * @param props - Initiative properties including spec, plan, blueprints, and context objects.
+ * @param blueprint - The blueprint to use for the initiative context.
+ * @returns An Effect that yields the initialized Initiative.
+ */
+export const makeInitialized = (
+  props: Omit<Obj.MakeProps<typeof Initiative>, 'spec' | 'plan' | 'artifacts' | 'subscriptions' | 'chat'> &
+    Partial<Pick<Obj.MakeProps<typeof Initiative>, 'artifacts' | 'subscriptions'>> & {
+      spec: string;
+      blueprints?: Ref.Ref<Blueprint.Blueprint>[];
+      contextObjects?: Ref.Ref<Obj.Any>[];
+    },
+  blueprint: Blueprint.Blueprint,
+): Effect.Effect<Initiative, never, QueueService | Database.Service> =>
+  Effect.gen(function* () {
+    const initiative = Obj.make(Initiative, {
+      ...props,
+      spec: Ref.make(Text.make(props.spec)),
+      plan: Ref.make(makePlan({ tasks: [] })),
+      artifacts: props.artifacts ?? [],
+      subscriptions: props.subscriptions ?? [],
+    });
+    yield* Database.add(initiative);
+    const queue = yield* QueueService.createQueue<Message.Message | ContextBinding>();
+    const contextBinder = new AiContextBinder({ queue });
+    // TODO(dmaretskyi): Blueprint registry.
+    const initiativeBlueprint = yield* Database.add(Obj.clone(blueprint, { deep: true }));
+    yield* Effect.promise(() =>
+      contextBinder.bind({
+        blueprints: [Ref.make(initiativeBlueprint), ...(props.blueprints ?? [])],
+        objects: [Ref.make(initiative), ...(props.contextObjects ?? [])],
+      }),
+    );
+    const chat = yield* Database.add(
+      Chat.make({
+        queue: Ref.fromDXN(queue.dxn),
+      }),
+    );
+    yield* Database.add(
+      Relation.make(Chat.CompanionTo, {
+        [Relation.Source]: chat,
+        [Relation.Target]: initiative,
+      }),
+    );
+
+    const inputQueue = yield* QueueService.createQueue();
+
+    Obj.change(initiative, (initiative) => {
+      initiative.chat = Ref.make(chat);
+      initiative.queue = Ref.fromDXN(inputQueue.dxn);
+    });
+
+    return initiative;
+  });
+
+/**
+ * Resets the initiative chat history by rebuilding the chat context.
+ * Preserves the existing blueprints and objects from the current chat context.
+ *
+ * @param initiative - The initiative whose chat history should be reset. Must have an existing chat.
+ * @returns An Effect that resets the chat history.
+ */
+export const resetChatHistory = (
+  initiative: Initiative,
+): Effect.Effect<void, ObjectNotFoundError, QueueService | Database.Service> =>
+  Effect.gen(function* () {
+    invariant(initiative.chat, 'Initiative must have an existing chat to reset.');
+
+    const existingQueue = yield* initiative.chat.pipe(Database.load).pipe(
+      Effect.map((_) => _.queue),
+      Effect.flatMap(Database.load),
+    );
+    const existingContextBinder = yield* acquireReleaseResource(
+      () =>
+        new AiContextBinder({
+          queue: existingQueue,
+        }),
+    );
+    const blueprints = existingContextBinder.getBlueprints().map((blueprint) => Ref.make(blueprint));
+    const objects = existingContextBinder.getObjects().map((object) => Ref.make(object));
+
+    const queue = yield* QueueService.createQueue();
+    const contextBinder = new AiContextBinder({ queue });
+    yield* Effect.promise(() =>
+      contextBinder.bind({
+        blueprints,
+        objects,
+      }),
+    );
+    const chat = yield* Database.add(
+      Chat.make({
+        queue: Ref.fromDXN(queue.dxn),
+      }),
+    );
+    Obj.change(initiative, (initiative) => {
+      initiative.chat = Ref.make(chat);
+    });
+    yield* Database.add(
+      Relation.make(Chat.CompanionTo, {
+        [Relation.Source]: chat,
+        [Relation.Target]: initiative,
+      }),
+    );
+  }).pipe(Effect.scoped);
+
+export const getFromChatContext: Effect.Effect<Initiative, never, AiContextService> = Effect.gen(function* () {
+  const initiatives = yield* Function.pipe(AiContextService.findObjects(Initiative));
+  if (initiatives.length !== 1) {
+    throw new Error('There should be exactly one initiative in context. Got: ' + initiatives.length);
+  }
+  const initiative = initiatives[0];
+  return initiative;
+});

package/src/planning/blueprint.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Blueprint } from '@dxos/blueprints';
+
+import { updateTasks } from './functions';
+
+export const PlanningBlueprint = Blueprint.make({
+  key: 'dxos.org/blueprint/planning',
+  name: 'Planning',
+  description: 'Plans and tracks complex tasks with artifact management.',
+  tools: Blueprint.toolDefinitions({ functions: [updateTasks] }),
+});

package/src/planning/functions/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { default as updateTasks } from './update-tasks';

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

@@ -0,0 +1,168 @@
+//
+// 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 { trim } from '@dxos/util';
+
+import * as Initiative from '../../initiative';
+
+const INSTRUCTIONS = trim`
+TASK MANAGEMENT TOOL - USAGE GUIDELINES
+
+This tool maintains an organized task list during work sessions to track progress, break down objectives, and ensure thoroughness. After creating initial tasks, update them silently without announcing changes to the user.
+
+=== 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 real-time 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.
+`;
+
+const TaskProps = Schema.Struct({
+  id: Initiative.TaskId,
+  title: Schema.String,
+  status: Schema.Literal('todo', 'in-progress', 'done'),
+});
+
+export default defineFunction({
+  key: 'dxos.org/function/planning/update-tasks',
+  name: 'Update tasks',
+  description: INSTRUCTIONS,
+  inputSchema: Schema.Struct({
+    tasks: Schema.Array(TaskProps),
+  }),
+  handler: Effect.fn(function* ({ data: { tasks: newTasks } }) {
+    const initiative = yield* Initiative.getFromChatContext;
+    const plan = yield* Database.load(initiative.plan);
+
+    Obj.change(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,
+          });
+        }
+      }
+    });
+
+    // console.log('\n====== TASKS ======\n');
+    // for (const task of tasks) {
+    //   console.log(`- **${task.status?.toLocaleUpperCase()}**: ${task.title ?? 'No title'} (id: ${task.id})`);
+    // }
+    // console.log('\n====== END TASKS ======\n');
+
+    return `
+      Tasks updated. Don't forget to mark tasks as done when you're done with them or update their status to 'in-progress' when you start working on them.
+      Current plan:
+      <plan>
+        ${Initiative.formatPlan(plan)}
+      </plan>
+    `;
+  }, AiContextService.fixFunctionHandlerType),
+});

package/src/planning/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { PlanningBlueprint } from './blueprint';
+export * as PlanningFunctions from './functions';

package/src/sync/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './sync';

package/src/sync/sync.ts

@@ -0,0 +1,95 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Filter, Obj, Query, Ref } from '@dxos/echo';
+import { Database } from '@dxos/echo';
+import { failedInvariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
+
+/**
+ * Syncs objects to the database.
+ * If there's an object with a matching foreign key in the database, it will be updated.
+ * Otherwise, a new object will be added.
+ * Recursively syncs top-level refs.
+ *
+ * @param opts.foreignKeyId - The key to use for matching objects.
+ */
+export const syncObjects: (
+  objs: Obj.Unknown[],
+  opts: { foreignKeyId: string },
+) => Effect.Effect<Obj.Unknown[], never, Database.Service> = Effect.fn('syncObjects')(function* (
+  objs,
+  { foreignKeyId },
+) {
+  return yield* Effect.forEach(
+    objs,
+    Effect.fnUntraced(function* (obj) {
+      // Sync referenced objects.
+      for (const key of Object.keys(obj)) {
+        if (typeof key !== 'string' || key === 'id') continue;
+        if (!Ref.isRef((obj as any)[key])) continue;
+        const ref: Ref.Unknown = (obj as any)[key];
+        if (!ref.target) continue;
+        if (Obj.getDXN(ref.target).isLocalObjectId()) {
+          // obj not persisted to db.
+          const [target] = yield* syncObjects([ref.target], { foreignKeyId });
+          (obj as any)[key] = Ref.make(target);
+        }
+      }
+
+      const schema = Obj.getSchema(obj) ?? failedInvariant('No schema.');
+      const foreignId = Obj.getKeys(obj, foreignKeyId)[0]?.id ?? failedInvariant('No foreign key.');
+      const [existing] = yield* Database.runQuery(
+        Query.select(Filter.foreignKeys(schema, [{ source: foreignKeyId, id: foreignId }])),
+      );
+      log('sync object', {
+        type: Obj.getTypename(obj),
+        foreignId,
+        existing: existing ? Obj.getDXN(existing) : undefined,
+      });
+      if (!existing) {
+        yield* Database.add(obj);
+        return obj;
+      } else {
+        copyObjectData(existing, obj);
+        return existing;
+      }
+    }),
+    { concurrency: 1 },
+  );
+});
+
+const copyObjectData = (existing: Obj.Unknown, newObj: Obj.Unknown) => {
+  Obj.change(existing, (obj) => {
+    // Copy properties from newObj to existing.
+    for (const key of Object.keys(newObj)) {
+      if (typeof key !== 'string' || key === 'id') continue;
+      if (
+        typeof (newObj as any)[key] !== 'string' &&
+        typeof (newObj as any)[key] !== 'number' &&
+        typeof (newObj as any)[key] !== 'boolean' &&
+        !Ref.isRef((newObj as any)[key])
+      )
+        continue;
+      (obj as any)[key] = (newObj as any)[key];
+    }
+
+    // Delete properties that don't exist in newObj.
+    for (const key of Object.keys(obj)) {
+      if (typeof key !== 'string' || key === 'id') continue;
+      if (!(key in newObj)) {
+        delete (obj as any)[key];
+      }
+    }
+
+    // Update foreign keys.
+    for (const foreignKey of Obj.getMeta(newObj).keys) {
+      Obj.deleteKeys(obj, foreignKey.source);
+      // TODO(dmaretskyi): Doesn't work: `Obj.getMeta(existing).keys.push(foreignKey);`
+      Obj.getMeta(obj).keys.push({ ...foreignKey });
+    }
+  });
+};

package/src/testing/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './plugins';

package/src/testing/plugins.tsx

@@ -0,0 +1,69 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import React from 'react';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Surface } from '@dxos/app-framework/ui';
+import { Format, type Obj, Type } from '@dxos/echo';
+import { JsonFilter } from '@dxos/react-ui-syntax-highlighter';
+
+export const MapSchema = Schema.Struct({
+  coordinates: Format.GeoPoint,
+}).pipe(
+  Type.object({
+    typename: 'example.com/type/Map',
+    version: '0.1.0',
+  }),
+);
+
+export type MapSchema = Schema.Schema.Type<typeof MapSchema>;
+
+// TODO(burdon): Move to ECHO def.
+export type ArtifactsContext = {
+  items: Obj.Unknown[];
+  getArtifacts: () => Obj.Unknown[];
+  addArtifact: (artifact: Obj.Unknown) => void;
+};
+
+declare global {
+  interface ToolContextExtensions {
+    artifacts?: ArtifactsContext;
+  }
+}
+
+// TODO(dmaretskyi): Removed images from conductor GPT implementation.
+const isImage = (data: any): data is any => false;
+
+export const capabilities: Capability.Any[] = [
+  Capability.contributes(
+    Capabilities.ReactSurface,
+    Surface.create({
+      id: 'plugin-image',
+      role: 'card--extrinsic',
+      filter: (data: any): data is any => isImage(data.value),
+      component: ({ data }) => (
+        <img
+          className='grow object-cover'
+          src={`data:image/jpeg;base64,${data.value.source.data}`}
+          alt={data.value.prompt ?? `Generated image [id=${data.value.id}]`}
+        />
+      ),
+    }),
+  ),
+
+  //
+  // Default
+  //
+  Capability.contributes(
+    Capabilities.ReactSurface,
+    Surface.create({
+      id: 'plugin-default',
+      role: 'card--extrinsic',
+      position: 'fallback',
+      component: ({ data }) => <JsonFilter data={data} />,
+    }),
+  ),
+];

package/src/toolkits/AssistantToolkit.conversations.json

@@ -0,0 +1 @@
+{"conversations":[{"parameters":{"model":"@anthropic/claude-opus-4-0","stream":true,"tools":[]},"prompt":{"content":[{"role":"system","content":"## Blueprints Definitions\n\n<blueprint>\n  \n</blueprint>","options":{}},{"role":"user","content":"Add to context: {\"id\":\"01JGFJJZ00G0WKQSJGMAKCNT8D\",\"@type\":\"dxn:type:dxos.org/type/Organization:0.1.0\",\"@meta\":{\"keys\":[]},\"name\":\"Cyberdyne Systems\",\"website\":\"https://cyberdyne.com\"}","options":{"anthropic":{"cacheControl":{"ttl":"5m","type":"ephemeral"}}}}]},"response":[{"type":"response-metadata","id":"msg_01ESZ2RnTWWshCN6AuVjhxBW","modelId":"claude-opus-4-20250514","timestamp":"1970-01-01T00:00:00.000Z","metadata":{}},{"type":"reasoning-start","id":"0","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"The user is adding","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" an","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" Organization","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" object","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" to the context.","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" This","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" appears","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" to be a DXOS object","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" with:","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"\n- An","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" ID","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"\n- A type designation","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" (@","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"type)","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" indicating","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" it's an Organization type version","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" 0.1.0\n-","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" Metadata with","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" an","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" empty keys array\n- A name:","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" \"Cyberdyne Systems\"","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"\n- A website: \"https://cyb","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"erdyne.com\"\n\nI shoul","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"d acknowledge that","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" this","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" has","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" been added to the context and be","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" ready to reference","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" or work","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" with this organization data","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" as","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" needed.","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"","metadata":{"anthropic":{"type":"thinking","signature":"EswECkYICxgCKkAKoUuFWE5zJ6soltEFAuI6miLz75XAO+fhBFkck5nOV8Zgw+xtXu+lcLNKF9T+nYU005q7jufvyi6dUAL4VAbDEgxQiKz084T8/HxIiC0aDGHf4286rPMhEleyDyIwW+6ZQtEfTq8gYiaaOpyqPRwa3cPy26HMeKj/1BXdMW9MJDcjxj02kjji0a4BV8AzKrMD6vSRsoAjP6ql8CxTqD91VvFiLqs4rqhHOVwlmmKVygRMogk5RvvRG/T4QzEGZSd7Xcl8yB19i03q3kpErfJu6b8+mFhndVcgBbFeFoGAA9aAJleUTdyLKvx/hSexzF0Th7xEdP1VTM4//JVq3lXB2LqqJzih7wTbqTn92vq5leNtGDoKJwnFdNvoxixY+HgB1JKSfsSGkZolby5yOp6kG52/2okeJfokgYpIjAxny8KjVq7SHsD9o9fLrKuA3VtzwG9eBBtK5t11bJoGQF+vGEmIwha35riPZIvzpa+SAbY4bU9QtMOnqn21fwYyhur/5WPXMZl3AsvJSi8yDcUrCbjsYcIxcn8lbCdbKA4sLMtQimREj7NU8onkj9ymivbG5CgluFohwpTFKyX4SNKd9MYdtE31Acmop2Zi2iHJQ+d/jH7tn503qoCeHV6LkMEEd0oFN5qHqRA5N0SBdKWrHzmlbBT4IHM4TvEwMINkzqf3J4TkCCwj727G4g7qepboMHiqtVYt5+HsQIZ3g8vR6hMTBoJn7qVUCWb67PImJNNQDzXoumvVEpHi9ZUI/rzJf+a8GAE="}}},{"type":"reasoning-end","id":"0","metadata":{}},{"type":"text-start","id":"1","metadata":{}},{"type":"text-delta","id":"1","delta":"I've added the Cyb","metadata":{}},{"type":"text-delta","id":"1","delta":"erdyne Systems organization object","metadata":{}},{"type":"text-delta","id":"1","delta":" to the","metadata":{}},{"type":"text-delta","id":"1","delta":" context. This","metadata":{}},{"type":"text-delta","id":"1","delta":" organization","metadata":{}},{"type":"text-delta","id":"1","delta":" has","metadata":{}},{"type":"text-delta","id":"1","delta":":","metadata":{}},{"type":"text-delta","id":"1","delta":"\n- Name","metadata":{}},{"type":"text-delta","id":"1","delta":": Cyberdyne Systems\n-","metadata":{}},{"type":"text-delta","id":"1","delta":" Website: https://cyberdyne.","metadata":{}},{"type":"text-delta","id":"1","delta":"com\n- Type: dxos","metadata":{}},{"type":"text-delta","id":"1","delta":".org/type/Organization:0","metadata":{}},{"type":"text-delta","id":"1","delta":".1.0","metadata":{}},{"type":"text-delta","id":"1","delta":"\n- ID: 01JG","metadata":{}},{"type":"text-delta","id":"1","delta":"FJJZ00G0W","metadata":{}},{"type":"text-delta","id":"1","delta":"KQSJGMAKCNT8","metadata":{}},{"type":"text-delta","id":"1","delta":"D\n\nI","metadata":{}},{"type":"text-delta","id":"1","delta":" can now reference this organization data","metadata":{}},{"type":"text-delta","id":"1","delta":" in","metadata":{}},{"type":"text-delta","id":"1","delta":" any","metadata":{}},{"type":"text-delta","id":"1","delta":" subsequent","metadata":{}},{"type":"text-delta","id":"1","delta":" operations","metadata":{}},{"type":"text-delta","id":"1","delta":" or queries","metadata":{}},{"type":"text-delta","id":"1","delta":" you","metadata":{}},{"type":"text-delta","id":"1","delta":"'","metadata":{}},{"type":"text-delta","id":"1","delta":"d like to perform","metadata":{}},{"type":"text-delta","id":"1","delta":".","metadata":{}},{"type":"text-end","id":"1","metadata":{}},{"type":"finish","reason":"stop","usage":{"inputTokens":135,"outputTokens":224,"totalTokens":359},"metadata":{"anthropic":{"usage":{"cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":0},"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"input_tokens":135,"output_tokens":4,"server_tool_use":null,"service_tier":"standard"}}}}]},{"parameters":{"model":"@anthropic/claude-opus-4-0","stream":true,"tools":[{"name":"context-add","description":"Adds the object to the chat context.","inputSchema":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"The ID of the document to add.","examples":["dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","@dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","BM3FSHFOMJCHCG5QW7JTVKGYABD2GAA7G:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","01KG7R1ZXWFMWQ4DA1Q6TN1DG4"]}},"additionalProperties":false}},{"name":"context-remove","description":"Removes the object from the chat context.","inputSchema":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"The ID of the document to remove.","examples":["dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","@dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","BM3FSHFOMJCHCG5QW7JTVKGYABD2GAA7G:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","01KG7R1ZXWFMWQ4DA1Q6TN1DG4"]}},"additionalProperties":false}}]},"prompt":{"content":[{"role":"system","content":"## Blueprints Definitions\n\n<blueprint>\n  \n</blueprint>","options":{}},{"role":"user","content":"Add to context: {\"id\":\"01JGFJJZ00G0WKQSJGMAKCNT8D\",\"@type\":\"dxn:type:dxos.org/type/Organization:0.1.0\",\"@meta\":{\"keys\":[]},\"name\":\"Cyberdyne Systems\",\"website\":\"https://cyberdyne.com\"}","options":{"anthropic":{"cacheControl":{"ttl":"5m","type":"ephemeral"}}}}]},"response":[{"type":"response-metadata","id":"msg_01PwdqJ4KYGWGo88Bpgkcb1b","modelId":"claude-opus-4-20250514","timestamp":"1970-01-01T00:00:00.000Z","metadata":{}},{"type":"reasoning-start","id":"0","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"The user wants to add an object to","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" the context. The","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" object has:","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"\n- id: \"01J","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"GFJJZ00G0","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"WKQSJGMAKCNT","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"8D\"\n- It","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"'s an","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" Organization type object","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"\n- name","metadata":{}},{"type":"reasoning-delta","id":"0","delta":": \"Cyberdyne Systems\"","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"\n- website: \"https://cyb","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"erdyne.com\"\n\nI nee","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"d to use the context-add function with","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" the","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" id parameter.","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"","metadata":{"anthropic":{"type":"thinking","signature":"EqkDCkYICxgCKkDRhGEp8nE9S2hhdiFom4JqAoWxdW/nKv7jjNB9Uybh5aeqVE13x2HhOoQJMWph3asUEzzt5B15yGTfoKc9lHSCEgytP588WsRipnT22dIaDFQPA72QE/XIbvEA+CIwxPckN1BzzMGgibUZmFKXxBdos3WMVBf2RpenWMQSppU+Ese4HQmltoQmp9zf7lj0KpAC1ZJP/lOSBxUTXS8BZWa7nOPclHVSohW2Ug8mul/NfMEDawimCvkkVYRRrdZQp1IeG/+kvJG7rQbgYsDU6SXN4zdPKcYtjv9wfIpRT6f200g1iBqRr1qKiMhLKpFNcAsOUaNQDXhKhr/A6ZhH4gaovEw65v10fyeUoHGzUHrDAEpy8cYDvzF/3TPEJhe3zIBw60cepyLaEZy+Z/1qmY2lsEqrkh95rv9WFASlB30nm762InotIIkAsMlxXY1xI0n+AZgh/ypPqyqaGiMVZ8aHKVLiCkBE1uTZszZBh7L2raEXK6znKVNSA4SiN33Mwzw7kEBBFrsuhrQnKqg8l5GaNqaE77knShQAXkzQYmgy8FMYAQ=="}}},{"type":"reasoning-end","id":"0","metadata":{}},{"type":"text-start","id":"1","metadata":{}},{"type":"text-delta","id":"1","delta":"I'll add this Organization","metadata":{}},{"type":"text-delta","id":"1","delta":" object to the context for you.","metadata":{}},{"type":"text-end","id":"1","metadata":{}},{"type":"tool-params-start","id":"toolu_01P7myKvWntosLM6RtWwKZGA","name":"context-add","providerExecuted":false,"metadata":{}},{"type":"tool-params-delta","id":"toolu_01P7myKvWntosLM6RtWwKZGA","delta":"","metadata":{}},{"type":"tool-params-delta","id":"toolu_01P7myKvWntosLM6RtWwKZGA","delta":"{\"id\": \"01JG","metadata":{}},{"type":"tool-params-delta","id":"toolu_01P7myKvWntosLM6RtWwKZGA","delta":"FJJZ00G0WKQ","metadata":{}},{"type":"tool-params-delta","id":"toolu_01P7myKvWntosLM6RtWwKZGA","delta":"SJGMAK","metadata":{}},{"type":"tool-params-delta","id":"toolu_01P7myKvWntosLM6RtWwKZGA","delta":"CNT8D\"}","metadata":{}},{"type":"tool-params-end","id":"toolu_01P7myKvWntosLM6RtWwKZGA","metadata":{}},{"type":"tool-call","id":"toolu_01P7myKvWntosLM6RtWwKZGA","name":"context-add","params":{"id":"01JGFJJZ00G0WKQSJGMAKCNT8D"},"providerExecuted":false,"metadata":{}},{"type":"finish","reason":"tool-calls","usage":{"inputTokens":911,"outputTokens":183,"totalTokens":1094},"metadata":{"anthropic":{"usage":{"cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":0},"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"input_tokens":911,"output_tokens":8,"server_tool_use":null,"service_tier":"standard"}}}}]},{"parameters":{"model":"@anthropic/claude-opus-4-0","stream":true,"tools":[{"name":"context-add","description":"Adds the object to the chat context.","inputSchema":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"The ID of the document to add.","examples":["dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","@dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","BM3FSHFOMJCHCG5QW7JTVKGYABD2GAA7G:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","01KG7R1ZXWFMWQ4DA1Q6TN1DG4"]}},"additionalProperties":false}},{"name":"context-remove","description":"Removes the object from the chat context.","inputSchema":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"The ID of the document to remove.","examples":["dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","@dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","BM3FSHFOMJCHCG5QW7JTVKGYABD2GAA7G:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","01KG7R1ZXWFMWQ4DA1Q6TN1DG4"]}},"additionalProperties":false}}]},"prompt":{"content":[{"role":"system","content":"## Blueprints Definitions\n\n<blueprint>\n  \n</blueprint>","options":{}},{"role":"user","content":"Add to context: {\"id\":\"01JGFJJZ00G0WKQSJGMAKCNT8D\",\"@type\":\"dxn:type:dxos.org/type/Organization:0.1.0\",\"@meta\":{\"keys\":[]},\"name\":\"Cyberdyne Systems\",\"website\":\"https://cyberdyne.com\"}","options":{}},{"role":"assistant","content":[{"type":"reasoning","text":"The user wants to add an object to the context. The object has:\n- id: \"01JGFJJZ00G0WKQSJGMAKCNT8D\"\n- It's an Organization type object\n- name: \"Cyberdyne Systems\"\n- website: \"https://cyberdyne.com\"\n\nI need to use the context-add function with the id parameter.","options":{}},{"type":"text","text":"I'll add this Organization object to the context for you.","options":{}},{"type":"tool-call","id":"toolu_01P7myKvWntosLM6RtWwKZGA","name":"context-add","params":{"id":"01JGFJJZ00G0WKQSJGMAKCNT8D"},"providerExecuted":false,"options":{}}],"options":{}},{"role":"tool","content":[{"type":"tool-result","id":"toolu_01P7myKvWntosLM6RtWwKZGA","name":"context-add","isFailure":false,"result":{},"providerExecuted":false,"options":{}}],"options":{"anthropic":{"cacheControl":{"ttl":"5m","type":"ephemeral"}}}}]},"response":[{"type":"response-metadata","id":"msg_01Rq8MMkzbb7kQcbuSf2pFcN","modelId":"claude-opus-4-20250514","timestamp":"1970-01-01T00:00:00.000Z","metadata":{}},{"type":"text-start","id":"0","metadata":{}},{"type":"text-delta","id":"0","delta":"I","metadata":{}},{"type":"text-delta","id":"0","delta":"'ve successfully added the","metadata":{}},{"type":"text-delta","id":"0","delta":" Cyberdyne Systems organization to the context","metadata":{}},{"type":"text-delta","id":"0","delta":". This","metadata":{}},{"type":"text-delta","id":"0","delta":" organization object includes:","metadata":{}},{"type":"text-delta","id":"0","delta":"\n- Name","metadata":{}},{"type":"text-delta","id":"0","delta":": Cyberdyne Systems\n-","metadata":{}},{"type":"text-delta","id":"0","delta":" Website: https://cyberdyne.","metadata":{}},{"type":"text-delta","id":"0","delta":"com\n- Type: Organization","metadata":{}},{"type":"text-delta","id":"0","delta":" (version","metadata":{}},{"type":"text-delta","id":"0","delta":" 0.1.0)","metadata":{}},{"type":"text-delta","id":"0","delta":"\n\nThe object is","metadata":{}},{"type":"text-delta","id":"0","delta":" now available","metadata":{}},{"type":"text-delta","id":"0","delta":" in the chat","metadata":{}},{"type":"text-delta","id":"0","delta":" context for","metadata":{}},{"type":"text-delta","id":"0","delta":" reference","metadata":{}},{"type":"text-delta","id":"0","delta":" and can","metadata":{}},{"type":"text-delta","id":"0","delta":" be used in our","metadata":{}},{"type":"text-delta","id":"0","delta":" conversation.","metadata":{}},{"type":"text-end","id":"0","metadata":{}},{"type":"finish","reason":"stop","usage":{"inputTokens":979,"outputTokens":77,"totalTokens":1056},"metadata":{"anthropic":{"usage":{"cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":0},"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"input_tokens":979,"output_tokens":1,"server_tool_use":null,"service_tier":"standard"}}}}]}]}

package/src/toolkits/AssistantToolkit.test.ts

@@ -0,0 +1,72 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { MemoizedAiService } from '@dxos/ai/testing';
+import { AiContextService, AiConversationService, GenericToolkit } from '@dxos/assistant';
+import { AssistantTestLayer } from '@dxos/assistant/testing';
+import { waitForCondition } from '@dxos/async';
+import { Blueprint, Template } from '@dxos/blueprints';
+import { Database, Obj, Ref } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { ObjectId } from '@dxos/keys';
+import { Message, Organization, Person } from '@dxos/types';
+
+import * as AssistantToolkit from './AssistantToolkit';
+
+ObjectId.dangerouslyDisableRandomness();
+
+const TestLayer = AssistantTestLayer({
+  types: [Blueprint.Blueprint, Message.Message, Person.Person, Organization.Organization],
+  toolkits: [GenericToolkit.make(AssistantToolkit.AssistantToolkit, AssistantToolkit.layer())],
+  tracing: 'pretty',
+});
+
+const blueprint = Blueprint.make({
+  key: 'dxos.org/blueprint/assistant',
+  name: 'Assistant',
+  tools: Blueprint.toolDefinitions({ tools: AssistantToolkit.tools }),
+  instructions: Template.make(),
+});
+
+describe('AssistantToolkit', () => {
+  it.scoped(
+    'can add to context',
+    Effect.fnUntraced(
+      function* (_) {
+        yield* AiContextService.bindContext({
+          blueprints: [Ref.make(yield* Database.add(blueprint))],
+        });
+
+        const organization = yield* Database.add(
+          Obj.make(Organization.Organization, {
+            name: 'Cyberdyne Systems',
+            website: 'https://cyberdyne.com',
+          }),
+        );
+
+        yield* AiConversationService.run({
+          prompt: `Add to context: ${JSON.stringify(organization)}`,
+        });
+
+        const { binder } = yield* AiContextService;
+        yield* Effect.promise(() =>
+          waitForCondition({
+            condition: () => binder.getBlueprints().length > 0 && binder.getObjects().length > 0,
+            timeout: 10_000,
+          }),
+        );
+
+        expect(binder.getBlueprints()).toEqual([blueprint]);
+        expect(binder.getObjects()).toEqual([organization]);
+      },
+      Effect.provide(AiConversationService.layerNewQueue().pipe(Layer.provideMerge(TestLayer))),
+      TestHelpers.provideTestContext,
+    ),
+    MemoizedAiService.isGenerationEnabled() ? 60_000 : undefined,
+  );
+});