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

package/src/types/Agent.ts

@@ -0,0 +1,239 @@
+//
+// 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/compute';
+import { QueueService } from '@dxos/compute';
+import { Annotation, Database, Feed, Format, 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 { 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),
+
+  /**
+   * When false, agent triggers are disabled after sync-triggers runs.
+   */
+  enabled: Schema.optional(Schema.Boolean).annotations({
+    title: 'Enabled',
+    description: 'Master switch for agent automation; propagated to all triggers on sync.',
+  }),
+
+  /**
+   * Instructions for the agent.
+   */
+  instructions: Ref.Ref(Text.Text).pipe(
+    Format.FormatAnnotation.set(Format.TypeFormat.Markdown),
+    Schema.annotations({ title: 'Instructions' }),
+  ),
+
+  /**
+   * 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? Should it be an artifact?
+  // Format.FormatAnnotation.set(Format.TypeFormat.Markdown)
+  plan: Ref.Ref(Plan.Plan).pipe(FormInputAnnotation.set(false)),
+
+  // TODO(burdon): Currently Memory.Memory objects are global to the space; make them artifacts?
+  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.',
+  }),
+
+  /**
+   * Cron expression for a timer trigger that invokes the agent worker on a schedule.
+   * The timer trigger bypasses the qualifier and goes straight to the agent worker.
+   */
+  cron: Schema.optional(Schema.String).annotations({
+    title: 'Cron',
+    description: 'Cron expression for a timer trigger that invokes the agent on a schedule.',
+  }),
+}).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,
+      enabled: props.enabled ?? 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.update(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.update(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,63 @@
+//
+// 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)),
+  view: Schema.String.pipe(Schema.optional),
+}).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.update` 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.update(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';