@dxos/assistant-toolkit 0.8.4-main.e8ec1fe → 0.8.4-main.fcfe5033a5

package/src/testing/plugins.tsx

@@ -0,0 +1,77 @@
+//
+// 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 { Card } from '@dxos/react-ui';
+import { Json } from '@dxos/react-ui-syntax-highlighter';
+
+export const MapSchema = Schema.Struct({
+  coordinates: Format.GeoPoint,
+}).pipe(
+  Type.object({
+    typename: 'com.example.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--content',
+      filter: (data: any): data is any => isImage(data.value),
+      component: ({ data }) => (
+        <Card.Content>
+          <img
+            className='grow object-cover'
+            src={`data:image/jpeg;base64,${data.value.source.data}`}
+            alt={data.value.prompt ?? `Generated image [id=${data.value.id}]`}
+          />
+        </Card.Content>
+      ),
+    }),
+  ),
+  Capability.contributes(
+    Capabilities.ReactSurface,
+    Surface.create({
+      id: 'plugin-default',
+      role: 'card--content',
+      position: 'fallback',
+      component: ({ data }) => (
+        <Card.Content>
+          <Json.Root data={data}>
+            <Json.Content>
+              <Json.Filter />
+              <Json.Data />
+            </Json.Content>
+          </Json.Root>
+        </Card.Content>
+      ),
+    }),
+  ),
+];

package/src/toolkits/WebToolkit.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as AnthropicTool from '@effect/ai-anthropic/AnthropicTool';
+import * as Tool from '@effect/ai/Tool';
+import * as Toolkit from '@effect/ai/Toolkit';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+// TODO(dmaretskyi): Testing only.
+export const WebToolkit = Toolkit.make(
+  AnthropicTool.WebSearch_20250305({}).pipe(
+    // TODO(dmaretskyi): Effect bug -- provider-defined tools don't support annotations.
+    // ToolFormatter.assign({
+    //   debugFormatResult: (result) =>
+    //     Array.isArray(result) ? result.map(Struct.pick('title', 'type', 'url', 'page_age')) : result,
+    // }),
+  ),
+  Tool.make('WebFetch', {
+    parameters: {
+      url: Schema.String,
+    },
+    success: Schema.String,
+  }),
+);
+
+export const layer = WebToolkit.toLayer({
+  WebFetch: Effect.fnUntraced(function* ({ url }) {
+    const response = yield* Effect.promise(() => fetch(url).then((response) => response.text()));
+    return response;
+  }),
+});

package/src/toolkits/index.ts

@@ -2,5 +2,4 @@
 // Copyright 2025 DXOS.org
 //
 
-export * as AssistantToolkit from './AssistantToolkit';
-export * as SystemToolkit from './SystemToolkit';
+export * as WebToolkit from './WebToolkit';

package/src/types/Agent.ts

@@ -0,0 +1,219 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Effect from 'effect/Effect';
+import * as Function from 'effect/Function';
+import * as Schema from 'effect/Schema';
+
+import { AiContextBinder, AiContextService } from '@dxos/assistant';
+import { type Blueprint } from '@dxos/blueprints';
+import { Annotation, Database, Feed, Obj, Ref, Relation, Type } from '@dxos/echo';
+import { Queue } from '@dxos/echo-db';
+import { type ObjectNotFoundError } from '@dxos/echo/Err';
+import { FormInputAnnotation, LabelAnnotation } from '@dxos/echo/internal';
+import { acquireReleaseResource } from '@dxos/effect';
+import { QueueService } from '@dxos/functions';
+import { invariant } from '@dxos/invariant';
+import { QueueAnnotation, Text } from '@dxos/schema';
+
+import * as Chat from './Chat';
+import * as Plan from './Plan';
+
+/**
+ * Agent schema definition.
+ */
+export const Agent = Schema.Struct({
+  name: Schema.optional(Schema.String),
+
+  /**
+   * Instructions for the agent.
+   */
+  instructions: Ref.Ref(Text.Text).pipe(FormInputAnnotation.set(false)),
+
+  /**
+   * Primary chat for the agent.
+   */
+  // TODO(dmaretskyi): Multiple chats; RB: branching hierarchy.
+  chat: Schema.optional(Ref.Ref(Chat.Chat).pipe(FormInputAnnotation.set(false))),
+
+  // TODO(burdon): Is this used?
+  plan: Ref.Ref(Plan.Plan).pipe(FormInputAnnotation.set(false)),
+
+  // TODO(burdon): Currently Memory.Memory objects are global to the space.
+
+  // TODO(burdon): Create ref to document to manage memories.
+  artifacts: Schema.Array(
+    Schema.Struct({
+      // TODO(dmaretskyi): Consider gettings names from the artifact itself using Obj.getLabel.
+      name: Schema.String,
+      // TODO(burdon): Rename object.
+      data: Ref.Ref(Obj.Unknown),
+    }),
+  ).pipe(FormInputAnnotation.set(false)),
+
+  /**
+   * Input feed for subscriptions.
+   */
+  // TODO(burdon): Rename to Feed?
+  // NOTE: Named `queue` to conform to subscribable schema (see QueueAnnotation).
+  queue: Schema.optional(Ref.Ref(Queue).pipe(FormInputAnnotation.set(false))),
+
+  /**
+   * References to objects with a canonical queue property.
+   * Schema must have the QueueAnnotation.
+   */
+  // TODO(dmaretskyi): Turn into an array of objects when form-data
+  subscriptions: Schema.Array(Ref.Ref(Obj.Unknown)).pipe(FormInputAnnotation.set(false)),
+
+  /**
+   * Allow the agent to filter events.
+   * Related events will be added to the input queue of the agent.
+   * It is recommended to enable this.
+   */
+  filterEvents: Schema.optional(Schema.Boolean).annotations({
+    title: 'Filter events',
+    description: 'Allow the agent to filter events.',
+  }),
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.agent',
+    version: '0.1.0',
+  }),
+  LabelAnnotation.set(['name']),
+  QueueAnnotation.set(true),
+  Annotation.IconAnnotation.set({
+    icon: 'ph--drone--regular',
+    hue: 'sky',
+  }),
+);
+
+export interface Agent extends Schema.Schema.Type<typeof Agent> {}
+
+/**
+ * Creates a fully initialized Agent with chat, queue, and context bindings.
+ *
+ * @param props - Agent properties including spec, plan, blueprints, and context objects.
+ * @param blueprint - The blueprint to use for the agent context.
+ * @returns An Effect that yields the initialized Agent.
+ */
+export const makeInitialized = (
+  props: Omit<Obj.MakeProps<typeof Agent>, 'instructions' | 'plan' | 'artifacts' | 'subscriptions' | 'chat'> &
+    Partial<Pick<Obj.MakeProps<typeof Agent>, 'artifacts' | 'subscriptions'>> & {
+      instructions: string;
+      blueprints?: Ref.Ref<Blueprint.Blueprint>[];
+      contextObjects?: Ref.Ref<Obj.Any>[];
+    },
+  blueprint: Blueprint.Blueprint,
+): Effect.Effect<Agent, never, QueueService | Feed.FeedService | Database.Service> =>
+  Effect.gen(function* () {
+    const agent = Obj.make(Agent, {
+      ...props,
+      instructions: Ref.make(Text.make(props.instructions)),
+      plan: Ref.make(Plan.makePlan({ tasks: [] })),
+      artifacts: props.artifacts ?? [],
+      subscriptions: props.subscriptions ?? [],
+      filterEvents: props.filterEvents ?? true,
+    });
+    yield* Database.add(agent);
+    const feed = yield* Database.add(Feed.make());
+    const runtime = yield* Effect.runtime<Feed.FeedService>();
+    const contextBinder = new AiContextBinder({ feed, runtime });
+    // TODO(dmaretskyi): Blueprint registry.
+    const agentBlueprint = yield* Database.add(Obj.clone(blueprint, { deep: true }));
+    yield* Effect.promise(() =>
+      contextBinder.bind({
+        blueprints: [Ref.make(agentBlueprint), ...(props.blueprints ?? [])],
+        objects: [Ref.make(agent), ...(props.contextObjects ?? [])],
+      }),
+    );
+    const chat = yield* Database.add(
+      Chat.make({
+        [Obj.Parent]: agent,
+        feed: Ref.make(feed),
+      }),
+    );
+    Obj.setParent(feed, chat);
+    yield* Database.add(
+      Relation.make(Chat.CompanionTo, {
+        [Relation.Source]: chat,
+        [Relation.Target]: agent,
+      }),
+    );
+
+    const inputQueue = yield* QueueService.createQueue();
+
+    Obj.change(agent, (agent) => {
+      agent.chat = Ref.make(chat);
+      agent.queue = Ref.fromDXN(inputQueue.dxn);
+    });
+
+    return agent;
+  });
+
+/**
+ * Resets the agent chat history by rebuilding the chat context.
+ * Preserves the existing blueprints and objects from the current chat context.
+ *
+ * @param agent - The agent whose chat history should be reset. Must have an existing chat.
+ * @returns An Effect that resets the chat history.
+ */
+export const resetChatHistory = (
+  agent: Agent,
+): Effect.Effect<void, ObjectNotFoundError, Feed.FeedService | Database.Service> =>
+  Effect.gen(function* () {
+    invariant(agent.chat, 'Agent must have an existing chat to reset.');
+
+    const existingFeed = yield* agent.chat.pipe(Database.load).pipe(
+      Effect.map((_) => _.feed),
+      Effect.flatMap(Database.load),
+    );
+    const runtime = yield* Effect.runtime<Feed.FeedService>();
+    const existingContextBinder = yield* acquireReleaseResource(
+      () =>
+        new AiContextBinder({
+          feed: existingFeed,
+          runtime,
+        }),
+    );
+    const blueprints = existingContextBinder.getBlueprints().map((blueprint) => Ref.make(blueprint));
+    const objects = existingContextBinder.getObjects().map((object) => Ref.make(object));
+
+    const feed = yield* Database.add(Feed.make());
+    const contextBinder = new AiContextBinder({ feed, runtime });
+    yield* Effect.promise(() =>
+      contextBinder.bind({
+        blueprints,
+        objects,
+      }),
+    );
+
+    const chat = yield* Database.add(
+      Chat.make({
+        feed: Ref.make(feed),
+      }),
+    );
+    Obj.setParent(feed, chat);
+    Obj.change(agent, (agent) => {
+      agent.chat = Ref.make(chat);
+    });
+
+    yield* Database.add(
+      Relation.make(Chat.CompanionTo, {
+        [Relation.Source]: chat,
+        [Relation.Target]: agent,
+      }),
+    );
+  }).pipe(Effect.scoped);
+
+export const getFromChatContext: Effect.Effect<Agent, Error, AiContextService> = Effect.gen(function* () {
+  const agents = yield* Function.pipe(AiContextService.findObjects(Agent));
+  if (agents.length !== 1) {
+    return yield* Effect.fail(new Error(`There should be exactly one agent in context. Got: ${agents.length}`));
+  }
+
+  const agent = agents[0];
+  return agent;
+});

package/src/types/Chat.ts

@@ -0,0 +1,62 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { Annotation, Feed, Obj, Ref, Type } from '@dxos/echo';
+import { FormInputAnnotation, LabelAnnotation } from '@dxos/echo/internal';
+
+/**
+ * AI chat.
+ */
+export const Chat = Schema.Struct({
+  name: Schema.String.pipe(Schema.optional),
+  feed: Ref.Ref(Feed.Feed).pipe(FormInputAnnotation.set(false)),
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.assistant.chat',
+    version: '0.1.0',
+  }),
+  LabelAnnotation.set(['name']),
+  Annotation.IconAnnotation.set({
+    icon: 'ph--sparkle--regular',
+    hue: 'sky',
+  }),
+);
+
+export interface Chat extends Schema.Schema.Type<typeof Chat> {}
+
+export const make = (props: Obj.MakeProps<typeof Chat>) => Obj.make(Chat, props);
+
+/** @deprecated Use CompanionTo instead. */
+export const LegacyCompanionTo = Schema.Struct({
+  id: Obj.ID,
+}).pipe(
+  Type.relation({
+    typename: 'org.dxos.relation.assistant.companion-to',
+    version: '0.1.0',
+    source: Chat,
+    target: Obj.Unknown,
+  }),
+);
+
+export interface LegacyCompanionTo extends Schema.Schema.Type<typeof LegacyCompanionTo> {}
+
+/**
+ * Relation between a Chat and companion objects (e.g., artifacts).
+ */
+export const CompanionTo = Schema.Struct({
+  id: Obj.ID,
+}).pipe(
+  Type.relation({
+    typename: 'org.dxos.relation.assistant.companionTo',
+    version: '0.1.0',
+    source: Chat,
+    target: Obj.Unknown,
+  }),
+);
+
+export interface CompanionTo extends Schema.Schema.Type<typeof CompanionTo> {}

package/src/types/McpServer.ts

@@ -0,0 +1,37 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { Annotation, Type } from '@dxos/echo';
+import { LabelAnnotation } from '@dxos/echo/internal';
+
+/**
+ * MCP server configuration stored as a space-level ECHO object.
+ *
+ * NOTE: `apiKey` is stored in plaintext and replicated to all peers with access to the space.
+ * A future iteration should move secrets to per-device credential storage or use envelope encryption.
+ */
+export const McpServer = Schema.Struct({
+  name: Schema.String,
+  url: Schema.String,
+  protocol: Schema.Union(Schema.Literal('sse'), Schema.Literal('http')),
+  /** Stored in plaintext; replicated to all peers in the space. */
+  apiKey: Schema.optional(Schema.String),
+  enabled: Schema.optional(Schema.Boolean),
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.assistant.mcpServer',
+    version: '0.1.0',
+  }),
+  LabelAnnotation.set(['name']),
+  Annotation.IconAnnotation.set({
+    icon: 'ph--plugs-connected--regular',
+    hue: 'sky',
+  }),
+);
+
+export interface McpServer extends Schema.Schema.Type<typeof McpServer> {}

package/src/types/Memory.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Annotation, Type } from '@dxos/echo';
+
+/**
+ * Unit of knowledge generated by an agent.
+ */
+export const Memory = Schema.Struct({
+  title: Schema.String,
+  content: Schema.String,
+}).pipe(
+  Type.object({ typename: 'org.dxos.type.memory', version: '0.1.0' }),
+  Annotation.LabelAnnotation.set(['title']),
+  Annotation.IconAnnotation.set({
+    icon: 'ph--brain--regular',
+    hue: 'pink',
+  }),
+);
+
+export interface Memory extends Schema.Schema.Type<typeof Memory> {}

package/src/types/Plan.ts

@@ -0,0 +1,110 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { Annotation, Obj, Ref, Type } from '@dxos/echo';
+
+import * as Chat from './Chat';
+
+export const TaskId = Schema.String.pipe(Schema.brand('@dxos/assistant-toolkit/TaskId'));
+export type TaskId = Schema.Schema.Type<typeof TaskId>;
+
+export const Task = Schema.Struct({
+  /**
+   * Short task ID unique within the plan.
+   */
+  id: TaskId,
+
+  title: Schema.String.annotations({
+    description: 'Task title and description.',
+  }),
+
+  status: Schema.Literal('todo', 'in-progress', 'done'),
+
+  /**
+   * Parent task ID.
+   */
+  parent: Schema.optional(TaskId).annotations({
+    description: 'Parent task ID.',
+  }),
+
+  /**
+   * Chat object that this task is associated with.
+   */
+  chat: Schema.optional(Ref.Ref(Chat.Chat)),
+});
+export interface Task extends Schema.Schema.Type<typeof Task> {}
+
+/**
+ * Hierarchical collection of tasks for humans and agents to track progress.
+ */
+export const Plan = Schema.Struct({
+  tasks: Schema.Array(Task),
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.plan',
+    version: '0.1.0',
+  }),
+  Annotation.SystemTypeAnnotation.set(true),
+);
+export interface Plan extends Schema.Schema.Type<typeof Plan> {}
+
+export const generateTaskId = (plan: Plan): TaskId => {
+  const existingIds = plan.tasks
+    .map((task) => {
+      const [num, letter] = task.id.split('-');
+      return parseInt(num);
+    })
+    .filter((_) => !isNaN(_));
+  let newId;
+  if (existingIds.length === 0) {
+    newId = 1;
+  } else {
+    newId = Math.max(...existingIds) + 1;
+  }
+  // Add random suffix to avoid collisions.
+  return TaskId.make(`${newId}-${crypto.randomUUID().slice(0, 2)}`);
+};
+
+/**
+ * Add new tasks to a plan, generating IDs for new tasks.
+ * Use inside an `Obj.change` callback.
+ */
+export const addTasks = (
+  plan: Obj.Mutable<Plan>,
+  tasks: (Pick<Task, 'title'> & Partial<Pick<Task, 'status' | 'parent' | 'chat'>>)[],
+) => {
+  for (const task of tasks) {
+    const taskId = generateTaskId(plan);
+    plan.tasks.push({ id: taskId, ...task, status: task.status ?? 'todo' });
+  }
+  return plan;
+};
+
+interface MakePlanProps {
+  tasks: {
+    title: string;
+    status?: 'todo' | 'in-progress' | 'done';
+  }[];
+}
+
+export const makePlan = (props: MakePlanProps): Plan => {
+  const plan = Obj.make(Plan, { tasks: [] });
+  Obj.change(plan, (plan) => {
+    addTasks(plan, props.tasks);
+  });
+  return plan;
+};
+
+/**
+ * Formats plan to markdown format.
+ */
+export const formatPlan = (plan: Plan): string => {
+  return plan.tasks
+    .map((task) => `- **${task.status?.toLocaleUpperCase()}**: ${task.title ?? 'No title'} <!-- id=${task.id} -->`)
+    .join('\n');
+};

package/src/types/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * as Chat from './Chat';
+export * as Agent from './Agent';
+export * as McpServer from './McpServer';
+export * as Plan from './Plan';
+export * as Memory from './Memory';