@dxos/assistant-toolkit 0.8.4-main.bc674ce → 0.8.4-main.bcb3aa67d6

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--atom--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/Memory.ts

@@ -0,0 +1,23 @@
+//
+// 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: 'dxos.org/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/Project.ts

@@ -0,0 +1,208 @@
+//
+// 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, type ContextBinding } from '@dxos/assistant';
+import { type Blueprint } from '@dxos/blueprints';
+import { Annotation, Database, Feed, Obj, Ref, Relation, Type } from '@dxos/echo';
+import { type ObjectNotFoundError } from '@dxos/echo/Err';
+import { FormInputAnnotation } from '@dxos/echo/internal';
+import { Queue } from '@dxos/echo-db';
+import { acquireReleaseResource } from '@dxos/effect';
+import { QueueService } from '@dxos/functions';
+import { invariant } from '@dxos/invariant';
+import { QueueAnnotation, Text } from '@dxos/schema';
+import type { Message } from '@dxos/types';
+
+import * as Chat from './Chat';
+import * as Plan from './Plan';
+
+/**
+ * Project schema definition.
+ */
+export const Project = Schema.Struct({
+  name: Schema.String,
+
+  spec: Ref.Ref(Text.Text).pipe(FormInputAnnotation.set(false)),
+  plan: Ref.Ref(Plan.Plan).pipe(FormInputAnnotation.set(false)),
+
+  artifacts: Schema.Array(
+    Schema.Struct({
+      // TODO(dmaretskyi): Consider gettings names from the artifact itself using Obj.getLabel.
+      name: Schema.String,
+      data: Ref.Ref(Obj.Unknown),
+    }),
+  ).pipe(FormInputAnnotation.set(false)),
+
+  /**
+   * Incoming queue that the agent processes.
+   */
+  // NOTE: Named `queue` to conform to subscribable schema (see QueueAnnotation).
+  queue: Schema.optional(Ref.Ref(Queue).pipe(FormInputAnnotation.set(false))),
+
+  // TODO(dmaretskyi): Multiple chats.
+  chat: Schema.optional(Ref.Ref(Chat.Chat).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)),
+
+  useQualifyingAgent: Schema.optional(Schema.Boolean).annotations({
+    title: 'Use qualifying agent on subscriptions',
+    description:
+      'If enabled, the qualifying agent will be used to determine if the event is relevant to the project. Related events will be added to the input queue of the project. It is recommended to enable this.',
+  }),
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.project',
+    version: '0.1.0',
+  }),
+  Annotation.IconAnnotation.set({
+    icon: 'ph--circuitry--regular',
+    hue: 'sky',
+  }),
+  QueueAnnotation.set(true),
+);
+
+export interface Project extends Schema.Schema.Type<typeof Project> {}
+
+/**
+ * Creates a fully initialized Project with chat, queue, and context bindings.
+ *
+ * @param props - Project properties including spec, plan, blueprints, and context objects.
+ * @param blueprint - The blueprint to use for the project context.
+ * @returns An Effect that yields the initialized Project.
+ */
+// TODO(burdon): Rename make and move into Project.ts?
+export const makeInitialized = (
+  props: Omit<Obj.MakeProps<typeof Project>, 'spec' | 'plan' | 'artifacts' | 'subscriptions' | 'chat'> &
+    Partial<Pick<Obj.MakeProps<typeof Project>, 'artifacts' | 'subscriptions'>> & {
+      spec: string;
+      blueprints?: Ref.Ref<Blueprint.Blueprint>[];
+      contextObjects?: Ref.Ref<Obj.Any>[];
+    },
+  blueprint: Blueprint.Blueprint,
+): Effect.Effect<Project, never, QueueService | Database.Service> =>
+  Effect.gen(function* () {
+    const project = Obj.make(Project, {
+      ...props,
+      spec: Ref.make(Text.make(props.spec)),
+      plan: Ref.make(Plan.makePlan({ tasks: [] })),
+      artifacts: props.artifacts ?? [],
+      subscriptions: props.subscriptions ?? [],
+      useQualifyingAgent: props.useQualifyingAgent ?? true,
+    });
+    yield* Database.add(project);
+    const feed = yield* Database.add(Feed.make());
+    const feedQueueDxn = Feed.getQueueDxn(feed);
+    invariant(feedQueueDxn, 'Feed queue DXN not found.');
+    const queue = yield* QueueService.getQueue<Message.Message | ContextBinding>(feedQueueDxn);
+    const contextBinder = new AiContextBinder({ queue });
+    // TODO(dmaretskyi): Blueprint registry.
+    const projectBlueprint = yield* Database.add(Obj.clone(blueprint, { deep: true }));
+    yield* Effect.promise(() =>
+      contextBinder.bind({
+        blueprints: [Ref.make(projectBlueprint), ...(props.blueprints ?? [])],
+        objects: [Ref.make(project), ...(props.contextObjects ?? [])],
+      }),
+    );
+    const chat = yield* Database.add(
+      Chat.make({
+        [Obj.Parent]: project,
+        feed: Ref.make(feed),
+      }),
+    );
+    Obj.setParent(feed, chat);
+    yield* Database.add(
+      Relation.make(Chat.CompanionTo, {
+        [Relation.Source]: chat,
+        [Relation.Target]: project,
+      }),
+    );
+
+    const inputQueue = yield* QueueService.createQueue();
+
+    Obj.change(project, (project) => {
+      project.chat = Ref.make(chat);
+      project.queue = Ref.fromDXN(inputQueue.dxn);
+    });
+
+    return project;
+  });
+
+/**
+ * Resets the project chat history by rebuilding the chat context.
+ * Preserves the existing blueprints and objects from the current chat context.
+ *
+ * @param project - The project whose chat history should be reset. Must have an existing chat.
+ * @returns An Effect that resets the chat history.
+ */
+export const resetChatHistory = (
+  project: Project,
+): Effect.Effect<void, ObjectNotFoundError, QueueService | Database.Service> =>
+  Effect.gen(function* () {
+    invariant(project.chat, 'Project must have an existing chat to reset.');
+
+    const existingFeed = yield* project.chat.pipe(Database.load).pipe(
+      Effect.map((_) => _.feed),
+      Effect.flatMap(Database.load),
+    );
+    const existingQueueDxn = Feed.getQueueDxn(existingFeed);
+    invariant(existingQueueDxn, 'Existing feed queue DXN not found.');
+    const existingQueue = yield* QueueService.getQueue(existingQueueDxn);
+    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 feed = yield* Database.add(Feed.make());
+    const feedQueueDxn = Feed.getQueueDxn(feed);
+    invariant(feedQueueDxn, 'Feed queue DXN not found.');
+    const queue = yield* QueueService.getQueue(feedQueueDxn);
+    const contextBinder = new AiContextBinder({ queue });
+    yield* Effect.promise(() =>
+      contextBinder.bind({
+        blueprints,
+        objects,
+      }),
+    );
+    const chat = yield* Database.add(
+      Chat.make({
+        feed: Ref.make(feed),
+      }),
+    );
+    Obj.setParent(feed, chat);
+
+    Obj.change(project, (project) => {
+      project.chat = Ref.make(chat);
+    });
+
+    yield* Database.add(
+      Relation.make(Chat.CompanionTo, {
+        [Relation.Source]: chat,
+        [Relation.Target]: project,
+      }),
+    );
+  }).pipe(Effect.scoped);
+
+export const getFromChatContext: Effect.Effect<Project, never, AiContextService> = Effect.gen(function* () {
+  const projects = yield* Function.pipe(AiContextService.findObjects(Project));
+  if (projects.length !== 1) {
+    throw new Error('There should be exactly one project in context. Got: ' + projects.length);
+  }
+  const project = projects[0];
+  return project;
+});

package/src/types/index.ts

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