@dxos/assistant-toolkit 0.8.4-main.3c1ae3b → 0.8.4-main.3fbcb4aa9b

package/src/functions/index.ts

@@ -3,9 +3,3 @@
 //
 
 export * from './agent';
-export * from './discord';
-export * from './document';
-export * from './entity-extraction';
-export * from './linear';
-export * from './research';
-export * from './tasks';

package/src/index.ts

@@ -3,8 +3,8 @@
 //
 
 export * from './blueprints';
+export * from './crud';
 export * from './functions';
-export * from './plugins';
 export * from './sync';
-export * from './crud';
 export * from './toolkits';
+export * from './types';

package/src/sync/sync.ts

@@ -18,18 +18,27 @@ import { log } from '@dxos/log';
  * @param opts.foreignKeyId - The key to use for matching objects.
  */
 export const syncObjects: (
-  objs: Obj.Any[],
+  objs: Obj.Unknown[],
   opts: { foreignKeyId: string },
-) => Effect.Effect<Obj.Any[], never, Database.Service> = Effect.fn('syncObjects')(function* (objs, { foreignKeyId }) {
+) => 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.Any = (obj as any)[key];
-        if (!ref.target) continue;
+        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 });
@@ -39,7 +48,7 @@ export const syncObjects: (
 
       const schema = Obj.getSchema(obj) ?? failedInvariant('No schema.');
       const foreignId = Obj.getKeys(obj, foreignKeyId)[0]?.id ?? failedInvariant('No foreign key.');
-      const [existing] = yield* Database.Service.runQuery(
+      const [existing] = yield* Database.runQuery(
         Query.select(Filter.foreignKeys(schema, [{ source: foreignKeyId, id: foreignId }])),
       );
       log('sync object', {
@@ -48,7 +57,7 @@ export const syncObjects: (
         existing: existing ? Obj.getDXN(existing) : undefined,
       });
       if (!existing) {
-        yield* Database.Service.add(obj);
+        yield* Database.add(obj);
         return obj;
       } else {
         copyObjectData(existing, obj);
@@ -59,27 +68,39 @@ export const syncObjects: (
   );
 });
 
-const copyObjectData = (existing: Obj.Any, newObj: Obj.Any) => {
-  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;
-    (existing as any)[key] = (newObj as any)[key];
-  }
-  for (const key of Object.keys(existing)) {
-    if (typeof key !== 'string' || key === 'id') continue;
-    if (!(key in newObj)) {
-      delete (existing as any)[key];
+const copyObjectData = (existing: Obj.Unknown, newObj: Obj.Unknown) => {
+  Obj.update(existing, (existing) => {
+    // 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;
+      }
+      (existing as any)[key] = (newObj as any)[key];
+    }
+
+    // Delete properties that don't exist in newObj.
+    for (const key of Object.keys(existing)) {
+      if (typeof key !== 'string' || key === 'id') {
+        continue;
+      }
+      if (!(key in newObj)) {
+        delete (existing as any)[key];
+      }
+    }
+
+    // Update foreign keys.
+    for (const foreignKey of Obj.getMeta(newObj).keys) {
+      Obj.deleteKeys(existing, foreignKey.source);
+      // TODO(dmaretskyi): Doesn't work: `Obj.getMeta(existing).keys.push(foreignKey);`
+      Obj.getMeta(existing).keys.push({ ...foreignKey });
     }
-  }
-  for (const foreignKey of Obj.getMeta(newObj).keys) {
-    Obj.deleteKeys(existing, foreignKey.source);
-    // TODO(dmaretskyi): Doesn't work: `Obj.getMeta(existing).keys.push(foreignKey);`
-    Obj.getMeta(existing).keys.push({ ...foreignKey });
-  }
+  });
 };

package/src/testing/index.ts

@@ -2,4 +2,5 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './data';
+export * from '../blueprints/testing';
+export * from './plugins';

package/src/testing/plugins.tsx

@@ -0,0 +1,79 @@
+//
+// 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 { Syntax } 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>
+          <Syntax.Root data={data}>
+            <Syntax.Content>
+              <Syntax.Filter />
+              <Syntax.Viewport>
+                <Syntax.Code />
+              </Syntax.Viewport>
+            </Syntax.Content>
+          </Syntax.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,240 @@
+//
+// 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 { 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 } from '@dxos/echo/internal';
+import { acquireReleaseResource } from '@dxos/effect';
+import { QueueService } from '@dxos/functions';
+import { invariant } from '@dxos/invariant';
+import { 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)),
+
+  /**
+   * References to objects with a canonical queue property.
+   * Schema must have the QueueAnnotation.
+   */
+  // Change to trigger.
+  // TODO(dmaretskyi): Turn into an array of objects when form-data
+  subscriptions: Schema.Array(Ref.Ref(Obj.Unknown)).pipe(FormInputAnnotation.set(false)),
+
+  /**
+   * 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.
+   */
+  // Change to trigger.
+  cron: Schema.optional(Schema.String).annotations({
+    title: 'Cron',
+    description: 'Cron expression for a timer trigger that invokes the agent on a schedule.',
+  }),
+
+  /**
+   * Allow the agent to filter events.
+   * Related events will be added to the input queue of the agent.
+   * It is recommended to enable this.
+   * @deprecated
+   */
+  filterEvents: Schema.optional(Schema.Boolean).annotations({
+    title: 'Filter events',
+    description: 'Allow the agent to filter events.',
+  }),
+
+  /**
+   * Input feed for subscriptions.
+   * @deprecated Subscriptions will write directly to the agent.
+   */
+  queue: Schema.optional(Ref.Ref(Queue).pipe(FormInputAnnotation.set(false))),
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.agent',
+    version: '0.1.0',
+  }),
+  Annotation.LabelAnnotation.set(['name']),
+  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({ content: 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 { McpServer as McpServerSpec } from '@dxos/compute';
+import { Annotation, Type } from '@dxos/echo';
+import { LabelAnnotation } from '@dxos/echo/internal';
+
+/**
+ * MCP server configuration stored as a space-level ECHO object.
+ *
+ * Composes the canonical connection spec from `@dxos/compute` (`url`, `protocol`, `apiKey`)
+ * and adds instance-level fields (`name`, `enabled`) plus ECHO annotations.
+ *
+ * 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({
+  ...McpServerSpec.McpServer.fields,
+  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> {}