@dxos/assistant 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/session/AiSession.ts

@@ -0,0 +1,328 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import { type Registry as AtomRegistry } from '@effect-atom/atom-react';
+import * as Array from 'effect/Array';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Either from 'effect/Either';
+import { pipe } from 'effect/Function';
+import * as Layer from 'effect/Layer';
+import * as Record from 'effect/Record';
+import * as Runtime from 'effect/Runtime';
+
+import { type OpaqueToolkit, type ToolExecutionService, type ToolResolverService } from '@dxos/ai';
+import { type Blueprint, McpServer, Operation, Trace } from '@dxos/compute';
+import { Resource } from '@dxos/context';
+import { Database, Feed, Filter, Obj, Registry } from '@dxos/echo';
+import { EffectEx } from '@dxos/effect';
+import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
+import { McpToolkit } from '@dxos/mcp-client';
+import { Message, type ContentBlock } from '@dxos/types';
+
+import { ToolExecutionServices } from '../functions';
+import { AiRequest, type GenerationObserver, formatSystemPrompt } from '../request';
+import { McpServerError } from '../util';
+import * as AiContext from './AiContext';
+import { SessionLoader } from './SessionLoader';
+import { createToolkit } from './toolkit';
+
+export type RunProps<R = never> = {
+  prompt: string | ContentBlock.Any[];
+  system?: string;
+  observer?: GenerationObserver;
+  toolkit?: OpaqueToolkit.OpaqueToolkit<R>;
+
+  /**
+   * Space-level MCP servers to connect alongside blueprint-defined ones.
+   */
+  mcpServers?: readonly McpServer.McpServer[];
+};
+
+export type Options = {
+  feed: Feed.Feed;
+  runtime: Runtime.Runtime<Feed.FeedService>;
+  /** @effect-atom/atom-react Registry for reactive state. */
+  registry?: AtomRegistry.Registry;
+};
+
+/**
+ * Summarization threshold in tokens.
+ */
+// TODO(dmaretskyi): Take from model characteristics. opus has 200k max tokens.
+const SUMMARY_THRESHOLD = 80_000;
+
+/**
+ * Durable conversation state (initiated by users and agents) backed by a Feed.
+ * Executes tools based on AI responses and supports cancellation of in-progress requests.
+ */
+export class Session extends Resource {
+  /**
+   * Blueprints and objects bound to the session.
+   */
+  private readonly _binder: AiContext.Binder;
+  private readonly _feed: Feed.Feed;
+  private readonly _runtime: Runtime.Runtime<Feed.FeedService>;
+  private readonly _sessionLoader = new SessionLoader();
+
+  public constructor(options: Options) {
+    super();
+    this._feed = options.feed;
+    this._runtime = options.runtime;
+    invariant(this._feed);
+    invariant(this._runtime);
+    this._binder = new AiContext.Binder({
+      feed: this._feed,
+      runtime: this._runtime,
+      registry: options.registry,
+    });
+  }
+
+  protected override async _open(): Promise<void> {
+    await this._binder.open(this._ctx);
+  }
+
+  public get feed() {
+    return this._feed;
+  }
+
+  public get context() {
+    return this._binder;
+  }
+
+  public async getHistory(): Promise<Message.Message[]> {
+    const queryResult = await Runtime.runPromise(this._runtime)(Feed.query(this._feed, Filter.type(Message.Message)));
+    const items = await queryResult.run();
+    const messages = items.filter(Obj.instanceOf(Message.Message));
+    return Runtime.runPromise(this._runtime)(this._sessionLoader.reifyHistory(this._feed, messages));
+  }
+
+  getTools(): Effect.Effect<
+    Record<string, import('@effect/ai/Tool').Any>,
+    never,
+    ToolExecutionService | ToolResolverService
+  > {
+    return Effect.gen(this, function* () {
+      const toolkit = yield* createToolkit({ blueprints: this.context.getBlueprints() });
+      return toolkit.toolkit.tools;
+    }).pipe(Effect.orDie);
+  }
+
+  /**
+   * Not provided by default, since users might want to override them.
+   */
+  makeToolExecutionServices(): Layer.Layer<
+    ToolExecutionService | ToolResolverService,
+    never,
+    OpaqueToolkit.OpaqueToolkitProvider | Operation.Service | Registry.Service
+  > {
+    return ToolExecutionServices.pipe(
+      Layer.provide(Operation.withInvocationOptions({ conversation: Obj.getURI(this._feed) })),
+    );
+  }
+
+  /**
+   * Creates a new cancelable request effect.
+   */
+  public createRequest<R = never>(
+    params: RunProps<R>,
+  ): Effect.Effect<Message.Message[], AiRequest.RunError, AiRequest.RunRequirements | R> {
+    return Effect.gen(this, function* () {
+      const history = yield* Effect.promise(() => this.getHistory());
+      const blueprints = this.context.getBlueprints();
+      const objects = this.context.getObjects();
+
+      log('run', {
+        history: history.length,
+        blueprints: blueprints.length,
+        objects: objects.length,
+      });
+
+      const request = new AiRequest.Request({
+        summarizationThreshold: SUMMARY_THRESHOLD,
+        observer: params.observer,
+        onOutput: (message) =>
+          Effect.promise(() => Runtime.runPromise(this._runtime)(Feed.append(this._feed, [message]))),
+      });
+
+      yield* request.begin({
+        history,
+        blueprints,
+        objects,
+        prompt: params.prompt,
+        system: params.system,
+      });
+
+      // Turn loop: recompute toolkit and system prompt between turns to pick up dynamically enabled blueprints.
+      do {
+        yield* Effect.promise(() => this.context.sync());
+        const currentBlueprints = this.context.getBlueprints();
+        const mcps = yield* connectMcpServers(currentBlueprints, params.mcpServers);
+        const toolkit = yield* createToolkit({
+          toolkit: params.toolkit,
+          blueprints: currentBlueprints,
+          opaqueToolkits: mcps,
+        });
+
+        log('toolkit', { tools: Record.keys(toolkit.toolkit.tools) });
+        const system = yield* formatSystemPrompt({
+          system: params.system,
+          blueprints: currentBlueprints,
+          objects: this.context.getObjects(),
+        }).pipe(Effect.orDie);
+
+        const { done } = yield* request.runAgentTurn({ system, toolkit });
+        if (done) {
+          break;
+        }
+
+        yield* request.runTools({ toolkit });
+      } while (true);
+
+      log('result', {
+        messages: request.pending.length,
+        duration: request.duration,
+        toolCalls: request.toolCalls,
+      });
+
+      return [...request.pending];
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          Layer.succeed(AiContext.Service, {
+            binder: this.context,
+          }),
+          Layer.succeed(Service, this),
+          Operation.withInvocationOptions({ conversation: Obj.getURI(this._feed) }),
+        ),
+      ),
+      Effect.withSpan('AiSession.createRequest'),
+    );
+  }
+}
+
+/**
+ * Gives access to the ai session.
+ */
+export class Service extends Context.Tag('@dxos/assistant/AiSessionService')<Service, Session>() {
+  /**
+   * Create a new session layer from options.
+   */
+  static layer = (options: Options): Layer.Layer<Service | AiContext.Service> =>
+    aiContextFromSession.pipe(
+      Layer.provideMerge(
+        Layer.scoped(
+          Service,
+          Effect.gen(function* () {
+            const session = yield* EffectEx.acquireReleaseResource(() => new Session(options));
+            return session;
+          }),
+        ),
+      ),
+    );
+
+  /**
+   * Create a new session with a new feed.
+   */
+  static layerNewFeed = (
+    options?: Omit<Options, 'feed' | 'runtime'>,
+  ): Layer.Layer<Service | AiContext.Service, never, Database.Service | Feed.FeedService> =>
+    Layer.unwrapScoped(
+      Effect.gen(function* () {
+        const feed = yield* Database.add(Feed.make());
+        const runtime = yield* Effect.runtime<Feed.FeedService>();
+        return Service.layer({ ...options, feed, runtime });
+      }),
+    );
+
+  /**
+   * Run a prompt in the current session.
+   */
+  static run = <R = never>(
+    params: RunProps<R>,
+  ): Effect.Effect<Message.Message[], AiRequest.RunError, AiRequest.RunRequirements | Service | R> =>
+    Effect.gen(function* () {
+      const session = yield* Service;
+      return yield* session.createRequest(params);
+    });
+}
+
+const aiContextFromSession = Layer.effect(
+  AiContext.Service,
+  Effect.gen(function* () {
+    const session = yield* Service;
+    return {
+      binder: session.context,
+    };
+  }),
+);
+
+const connectMcpServers = (
+  blueprints: readonly Blueprint.Blueprint[],
+  spaceMcpServers: readonly McpServer.McpServer[] = [],
+): Effect.Effect<OpaqueToolkit.OpaqueToolkit[], never, Trace.TraceService> => {
+  const blueprintServers: McpToolkit.McpToolkitOptions[] = pipe(
+    blueprints,
+    Array.flatMap((_) => _.mcpServers ?? []),
+    Array.map(({ url, protocol, apiKey }) => ({ url, protocol, apiKey })),
+  );
+  const spaceServers: McpToolkit.McpToolkitOptions[] = spaceMcpServers.map(({ url, protocol, apiKey }) => ({
+    url,
+    protocol,
+    apiKey,
+  }));
+  const allServers = [...blueprintServers, ...spaceServers];
+
+  return pipe(
+    allServers,
+    Effect.forEach((options) =>
+      McpToolkit.make(options).pipe(
+        // NOTE: Type-inference fails here without explicit void return.
+        Effect.tap((toolkit): void =>
+          log.info('Connected to MCP server', { url: options.url, tools: Object.keys(toolkit.toolkit.tools).length }),
+        ),
+        // Surface typed connection failures via ephemeral trace + warn log, then drop the server.
+        Effect.tapError((error) =>
+          Effect.gen(function* () {
+            log.warn('Failed to connect to MCP server', {
+              url: error.url,
+              protocol: error.protocol,
+              message: error.message,
+            });
+            yield* Trace.write(McpServerError, {
+              url: error.url,
+              protocol: error.protocol,
+              message: error.message,
+            });
+          }),
+        ),
+        // Catch unexpected defects too (e.g. malformed tool schemas) so a single broken
+        // server can never abort the whole turn — surface them through the same channel.
+        Effect.catchAllDefect((defect) =>
+          Effect.gen(function* () {
+            const message = defect instanceof Error ? defect.message : String(defect);
+            log.warn('Unexpected MCP defect', { url: options.url, message });
+            yield* Trace.write(McpServerError, {
+              url: options.url,
+              protocol: options.protocol,
+              message: `Unexpected MCP failure: ${message}`,
+            });
+            return yield* Effect.fail(
+              new McpToolkit.McpConnectionError({
+                url: options.url,
+                protocol: options.protocol,
+                message,
+              }),
+            );
+          }),
+        ),
+        Effect.either,
+      ),
+    ),
+    Effect.map(Array.filterMap((_) => Either.getRight(_))),
+  );
+};

package/src/session/SessionLink.ts

@@ -0,0 +1,23 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { DXN, Feed, Obj, Ref, Type } from '@dxos/echo';
+
+/**
+ * Feed-level record that links this session to a point in another session's history.
+ * When present in a feed, the messages from the referenced feed up to and including
+ * `messageId` are prepended to the conversation history before each turn.
+ */
+export const SessionLink = Schema.Struct({
+  /** Reference to the feed of the source session. */
+  feedRef: Ref.Ref(Feed.Feed),
+  /** Messages from the source feed up to and including this message ID are injected. */
+  messageId: Obj.ID,
+}).pipe(Type.makeObject(DXN.make('org.dxos.type.sessionLink', '0.1.0')));
+
+export type SessionLink = Type.InstanceType<typeof SessionLink>;

package/src/session/SessionLoader.test.ts

@@ -0,0 +1,115 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { Database, Feed, Obj, Ref } from '@dxos/echo';
+import { TestDatabaseLayer } from '@dxos/echo-client/testing';
+import { Message } from '@dxos/types';
+
+import * as SessionLink from './SessionLink';
+import { SessionLoader } from './SessionLoader';
+
+// Monotonic timestamps so chronological sorting in SessionLoader is deterministic.
+let clock = 0;
+const makeMessage = (text: string, sender: 'user' | 'assistant' = 'user') =>
+  Message.make({ created: new Date(clock++).toISOString(), sender, blocks: [{ _tag: 'text', text }] });
+
+describe('SessionLoader', () => {
+  const TestLayer = TestDatabaseLayer({ types: [Feed.Feed, Message.Message, SessionLink.SessionLink] });
+
+  it.effect('returns original messages when no SessionLink exists in feed', () =>
+    Effect.gen(function* () {
+      const { db } = yield* Database.Service;
+      const feed = db.add(Feed.make());
+      const message = makeMessage('hello');
+      yield* Feed.append(feed, [message]);
+
+      const result = yield* new SessionLoader().reifyHistory(feed, [message]);
+
+      expect(result.map((msg) => msg.id)).toEqual([message.id]);
+    }).pipe(Effect.provide(TestLayer)),
+  );
+
+  it.effect('prepends source history when SessionLink resolves to a valid message', () =>
+    Effect.gen(function* () {
+      const { db } = yield* Database.Service;
+      const sourceFeed = db.add(Feed.make());
+      const forkFeed = db.add(Feed.make());
+
+      const msg1 = makeMessage('first');
+      const msg2 = makeMessage('second', 'assistant');
+      const forkMsg = makeMessage('new turn');
+      yield* Feed.append(sourceFeed, [msg1, msg2]);
+
+      yield* Feed.append(forkFeed, [
+        Obj.make(SessionLink.SessionLink, { feedRef: Ref.make(sourceFeed), messageId: msg2.id }),
+      ]);
+
+      const result = yield* new SessionLoader().reifyHistory(forkFeed, [forkMsg]);
+
+      expect(result.map((msg) => msg.id)).toEqual([msg1.id, msg2.id, forkMsg.id]);
+    }).pipe(Effect.provide(TestLayer)),
+  );
+
+  it.effect('respects the fork cutoff — excludes messages after messageId', () =>
+    Effect.gen(function* () {
+      const { db } = yield* Database.Service;
+      const sourceFeed = db.add(Feed.make());
+      const forkFeed = db.add(Feed.make());
+
+      const msg1 = makeMessage('a');
+      const msg2 = makeMessage('b', 'assistant');
+      const msg3 = makeMessage('c — after fork');
+      yield* Feed.append(sourceFeed, [msg1, msg2, msg3]);
+
+      yield* Feed.append(forkFeed, [
+        // Fork at msg2; msg3 should be excluded.
+        Obj.make(SessionLink.SessionLink, { feedRef: Ref.make(sourceFeed), messageId: msg2.id }),
+      ]);
+
+      const result = yield* new SessionLoader().reifyHistory(forkFeed, []);
+
+      expect(result.map((msg) => msg.id)).toEqual([msg1.id, msg2.id]);
+    }).pipe(Effect.provide(TestLayer)),
+  );
+
+  it.effect('returns original messages when messageId is not found in source feed (fail-closed)', () =>
+    Effect.gen(function* () {
+      const { db } = yield* Database.Service;
+      const sourceFeed = db.add(Feed.make());
+      const forkFeed = db.add(Feed.make());
+
+      const msg1 = makeMessage('existing');
+      const currentMsg = makeMessage('new turn');
+      yield* Feed.append(sourceFeed, [msg1]);
+
+      yield* Feed.append(forkFeed, [
+        Obj.make(SessionLink.SessionLink, { feedRef: Ref.make(sourceFeed), messageId: Obj.ID.random() }),
+      ]);
+
+      const result = yield* new SessionLoader().reifyHistory(forkFeed, [currentMsg]);
+
+      expect(result.map((msg) => msg.id)).toEqual([currentMsg.id]);
+    }).pipe(Effect.provide(TestLayer)),
+  );
+
+  it.effect('returns original messages when source feed reference is unresolvable', () =>
+    Effect.gen(function* () {
+      const { db } = yield* Database.Service;
+      const forkFeed = db.add(Feed.make());
+      const unresolvedFeed = Feed.make(); // Intentionally not added to the database.
+
+      yield* Feed.append(forkFeed, [
+        Obj.make(SessionLink.SessionLink, { feedRef: Ref.make(unresolvedFeed), messageId: Obj.ID.random() }),
+      ]);
+
+      const currentMsg = makeMessage('hello');
+      const result = yield* new SessionLoader().reifyHistory(forkFeed, [currentMsg]);
+
+      expect(result.map((msg) => msg.id)).toEqual([currentMsg.id]);
+    }).pipe(Effect.provide(TestLayer)),
+  );
+});

package/src/session/SessionLoader.ts

@@ -0,0 +1,55 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Feed, Filter, Obj } from '@dxos/echo';
+import { Message } from '@dxos/types';
+
+import * as SessionLink from './SessionLink';
+
+/**
+ * Loads and reifies conversation history by resolving SessionLink feed records.
+ */
+export class SessionLoader {
+  /**
+   * Prepends linked history to `messages` when the feed contains a SessionLink.
+   * Queries the feed for any SessionLink record; if found, loads messages from
+   * the referenced feed up to and including `messageId` and prepends them.
+   */
+  reifyHistory(
+    feed: Feed.Feed,
+    messages: Message.Message[],
+  ): Effect.Effect<Message.Message[], never, Feed.FeedService> {
+    return Effect.gen(function* () {
+      const links = yield* Feed.runQuery(feed, Filter.type(SessionLink.SessionLink));
+      const sessionLinks = links.filter(Obj.instanceOf(SessionLink.SessionLink));
+
+      const link = sessionLinks[0];
+      if (!link) {
+        return messages;
+      }
+
+      const sourceFeed = link.feedRef.target;
+      if (!sourceFeed) {
+        return messages;
+      }
+
+      const sourceMessages = yield* Feed.runQuery(sourceFeed, Filter.type(Message.Message));
+      const filtered = sourceMessages.filter(Obj.instanceOf(Message.Message));
+
+      // Sort by creation timestamp so history is in chronological order.
+      const sorted = [...filtered].sort((a, b) => a.created.localeCompare(b.created));
+
+      // Include messages up to and including the fork point.
+      const cutoffIndex = sorted.findIndex((m) => m.id === link.messageId);
+      if (cutoffIndex < 0) {
+        // Fork point not found; return original messages unmodified to avoid injecting unexpected history.
+        return messages;
+      }
+
+      return [...sorted.slice(0, cutoffIndex + 1), ...messages];
+    });
+  }
+}

package/src/session/index.ts

@@ -2,6 +2,9 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './artifact-diff';
-export * from './session';
-export * from './version-pin';
+export * from './toolkit';
+
+export * as AiContext from './AiContext';
+export * as AiSession from './AiSession';
+export { SessionLoader } from './SessionLoader';
+export * as SessionLink from './SessionLink';

package/src/session/toolkit.ts

@@ -0,0 +1,47 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Toolkit from '@effect/ai/Toolkit';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { type AiToolNotFoundError, OpaqueToolkit, ToolExecutionService, ToolResolverService } from '@dxos/ai';
+import { type Blueprint } from '@dxos/compute';
+import { isTruthy } from '@dxos/util';
+
+export type CreateToolkitProps = {
+  toolkit?: OpaqueToolkit.Any;
+  blueprints?: readonly Blueprint.Blueprint[];
+  /**
+   * Self-contained with handlers toolkits.
+   */
+  opaqueToolkits?: readonly OpaqueToolkit.Any[];
+};
+
+/**
+ * Build a combined toolkit from the blueprint tools and the provided toolkit.
+ */
+export const createToolkit = ({
+  toolkit: toolkitProp,
+  blueprints = [],
+  opaqueToolkits = [],
+}: CreateToolkitProps): Effect.Effect<
+  OpaqueToolkit.OpaqueToolkit,
+  AiToolNotFoundError,
+  ToolResolverService | ToolExecutionService
+> =>
+  Effect.gen(function* () {
+    const blueprintToolkit = yield* ToolResolverService.resolveToolkit(blueprints.flatMap(({ tools }) => tools));
+    const blueprintToolHandler = yield* blueprintToolkit.toContext(ToolExecutionService.handlersFor(blueprintToolkit));
+    const opaqueToolkit = OpaqueToolkit.merge(...opaqueToolkits);
+
+    const toolkitDefs = [toolkitProp?.toolkit, blueprintToolkit, opaqueToolkit.toolkit].filter(isTruthy);
+    const mergedToolkit = Toolkit.merge(...toolkitDefs);
+    const combinedHandlerLayer = Layer.mergeAll(
+      Layer.succeedContext(blueprintToolHandler),
+      toolkitProp?.layer ?? OpaqueToolkit.empty.layer,
+      opaqueToolkit.layer,
+    );
+    return OpaqueToolkit.make(mergedToolkit, combinedHandlerLayer as any) as OpaqueToolkit.OpaqueToolkit;
+  }) as Effect.Effect<OpaqueToolkit.OpaqueToolkit, AiToolNotFoundError, ToolResolverService | ToolExecutionService>;

package/src/templates/{format.tpl → instructions/format.tpl}

@@ -23,6 +23,7 @@ The <typename> element is the type of the object.
 It is very important to respond in the correct format.
 You response must be valid Markdown.
 In some cases you should respond with well-formed XML tags along with the content.
+Code snippets should use 2-space indents.
 
 {{#if cot}}
 Before responding, explain your reasoning and include your detailed chain-of-thought enclosed in a <cot> tag.
@@ -42,14 +43,15 @@ You can reply with a block reference for objects if you have the DXN. For exampl
 
 ### Suggestions
 
-Each suggestion must in the form of a proposed action enclosed in a <suggest> tag.
-Example: <suggest>Show on a map</suggest>
+Each suggestion must in the form of a proposed action enclosed in a <suggestion> tag.
+Example: <suggestion>Show on a map</suggestion>
+Do not use bullets when listing suggestions.
 
 ### Multiple choice questions
 
 You may ask multiple choice questions by wrapping consise options inside <option> tags inside a well formed <select> tag.
 Example: <select><option>Yes</option><option>No</option></select>
 
-## Toolkit
+## Context
 
-If the user asks for a list of tools, then just emit a single self-closing <toolkit/> tag instead of listing the tools.
+The current date and time is {{DATETIME}}.