@dxos/assistant 0.8.4-main.f9ba587 → 0.8.4-main.fffef41

package/src/session/GenericToolkit.ts

@@ -0,0 +1,130 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Tool from '@effect/ai/Tool';
+import * as Toolkit from '@effect/ai/Toolkit';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Pipeable from 'effect/Pipeable';
+import type * as Schema from 'effect/Schema';
+import type * as SchemaAST from 'effect/SchemaAST';
+
+/**
+ * Unique identifier for generic toolkit instances.
+ */
+export const TypeId = '~@dxos/assistant/GenericToolkit';
+
+/**
+ * Type-level representation of the generic toolkit identifier.
+ */
+export type TypeId = typeof TypeId;
+
+/**
+ * Type-safe way to define toolkits where we don't know specific types of tools,
+ * and we want to bundle definition and handlers together.
+ *
+ * Usefull for plugin-based systems, where tools are dynamically added.
+ *
+ * @param TR requirements type to the tool invocation.
+ * @param E failure type to the handlers layer.
+ * @param R requirements type to the handlers layer.
+ */
+export interface GenericToolkit<TR = never, E = never, R = never> extends Pipeable.Pipeable {
+  readonly [TypeId]: TypeId;
+
+  /**
+   * Toolkit definition.
+   */
+  readonly toolkit: Toolkit.Toolkit<GenericTools<TR>>;
+
+  /**
+   * Handlers layer.
+   */
+  readonly layer: Layer.Layer<unknown, E, R>;
+
+  /**
+   * Handlers effect.
+   */
+  readonly handlers: Effect.Effect<Toolkit.WithHandler<GenericTools<TR>>, E, R>;
+}
+
+/**
+ * Generic constraint.
+ *
+ * NOTE: Only use in place of `T extends PortableToolkit.Any`. Not suitable for standalone use.
+ */
+export interface Any {
+  readonly [TypeId]: TypeId;
+  readonly toolkit: Toolkit.Toolkit<any>;
+  readonly layer: Layer.Layer<unknown, any, any>;
+}
+
+export type InvocationRequirements<T extends Any> = T extends GenericToolkit<infer TR, infer _E, infer _R> ? TR : never;
+export type Failure<T extends Any> = T extends GenericToolkit<infer _TR, infer E, infer _R> ? E : never;
+export type Requirements<T extends Any> = T extends GenericToolkit<infer _TR, infer _E, infer R> ? R : never;
+
+/**
+ * Creates a portable toolkit from toolkit definition and handlers layer.
+ */
+export const make = <Tools extends Record<string, Tool.Any>, E, R>(
+  toolkit: Toolkit.Toolkit<Tools>,
+  layer: Layer.Layer<Tool.HandlersFor<Tools>, E, R>,
+): GenericToolkit<E, R> => {
+  return {
+    [TypeId]: TypeId,
+    toolkit: toolkit as any,
+    layer: layer as any,
+    handlers: toolkit.pipe(Effect.provide(layer)) as any,
+    pipe() {
+      // eslint-disable-next-line prefer-rest-params
+      return Pipeable.pipeArguments(this, arguments);
+    },
+  };
+};
+
+/**
+ * Merges multiple portable toolkits into a single portable toolkit.
+ */
+export const merge = <const Toolkits extends ReadonlyArray<Any>>(
+  /**
+   * The toolkits to merge together.
+   */
+  ...toolkits: Toolkits
+): GenericToolkit<
+  InvocationRequirements<Toolkits[number]>,
+  Failure<Toolkits[number]>,
+  Requirements<Toolkits[number]>
+> => {
+  return make(
+    Toolkit.merge(...toolkits.map((t) => t.toolkit)),
+    Layer.mergeAll(...(toolkits.map((t) => t.layer) as any)),
+  ) as any;
+};
+
+/**
+ * Generic tools type where we cannot statically enumerate individual tools.
+ */
+export type GenericTools<R = never> = Record<
+  string,
+  Tool.Tool<
+    string,
+    {
+      readonly parameters: AnyStructSchemaNoContext;
+      readonly success: Schema.Schema.AnyNoContext;
+      readonly failure: typeof Schema.Never;
+    },
+    R
+  >
+>;
+
+export interface AnyStructSchemaNoContext extends Pipeable.Pipeable {
+  readonly [Schema.TypeId]: any;
+  readonly make: any;
+  readonly Type: any;
+  readonly Encoded: any;
+  readonly Context: never;
+  readonly ast: SchemaAST.AST;
+  readonly fields: Schema.Struct.Fields;
+  readonly annotations: any;
+}

package/src/session/artifact-diff.ts

@@ -0,0 +1,41 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Context from 'effect/Context';
+
+import { type ObjectId } from '@dxos/echo/internal';
+import { type ObjectVersion } from '@dxos/echo-db';
+
+/**
+ * Resolves artifact ids to their versions.
+ * Used to give the model a sense of the changes to the artifacts made by users during the conversation.
+ * The artifacts versions are pinned in the history, and whenever the artifact changes in-between assistant's steps,
+ * a diff is inserted into the conversation.
+ *
+ * Can be optionally provided to the session run call.
+ */
+// TODO(dmaretskyi): Convert to Context.Reference
+export class ArtifactDiffResolver extends Context.Tag('@dxos/assistant/ArtifactDiffResolver')<
+  ArtifactDiffResolver,
+  ArtifactDiffResolver.Service
+>() {}
+
+export namespace ArtifactDiffResolver {
+  export type Service = {
+    resolve: (
+      artifacts: {
+        id: ObjectId;
+        lastVersion: ObjectVersion;
+      }[],
+    ) => Promise<
+      Map<
+        ObjectId,
+        {
+          version: ObjectVersion;
+          diff?: string;
+        }
+      >
+    >;
+  };
+}

package/src/session/error-handling.ts

@@ -0,0 +1,41 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as AiError from '@effect/ai/AiError';
+import * as HttpClientError from '@effect/platform/HttpClientError';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { AiModelError } from '../errors';
+
+const AnthropicErrorResponse = Schema.Struct({
+  type: Schema.Literal('error'),
+  error: Schema.Struct({
+    type: Schema.String,
+    message: Schema.String,
+  }),
+});
+
+// TODO(dmaretskyi): Needs rework
+export const mapAiError = (err: AiError.AiError): Effect.Effect<AiError.AiError> =>
+  Effect.gen(function* () {
+    const cause = err.cause;
+    if (HttpClientError.isHttpClientError(cause) && cause.reason === 'StatusCode') {
+      const body = yield* cause.response.json.pipe(
+        Effect.flatMap(Schema.decodeUnknown(AnthropicErrorResponse, { exact: false })),
+      );
+
+      const parsedCause = new AiModelError({
+        message: body.error.message,
+        context: { model: 'anthropic', type: body.error.type },
+      });
+      return AiError.UnknownError.make({
+        description: body.error.message,
+        module: err.module,
+        method: err.method,
+        cause: parsedCause,
+      });
+    }
+    return err;
+  }).pipe(Effect.catchAll(() => Effect.succeed(err)));

package/src/session/format.test.ts

@@ -0,0 +1,61 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { beforeAll, describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { Blueprint, Template } from '@dxos/blueprints';
+import { Obj } from '@dxos/echo';
+import { type EchoDatabase } from '@dxos/echo-db';
+import { EchoTestBuilder } from '@dxos/echo-db/testing';
+import { Text } from '@dxos/schema';
+import { Organization } from '@dxos/types';
+import { trim } from '@dxos/util';
+
+import { createSystemPrompt } from '../templates/system';
+
+import { formatSystemPrompt } from './format';
+
+describe('format', () => {
+  let db: EchoDatabase;
+  beforeAll(async () => {
+    const builder = await new EchoTestBuilder().open();
+    ({ db } = await builder.createDatabase({
+      types: [Text.Text, Organization.Organization, Blueprint.Blueprint],
+    }));
+  });
+
+  it.effect(
+    'should format',
+    Effect.fn(function* () {
+      const object = db.add(
+        Obj.make(Organization.Organization, {
+          name: 'Test',
+          website: 'https://www.test.com',
+        }),
+      );
+
+      const blueprint = db.add(
+        Blueprint.make({
+          key: 'example.com/blueprint/test',
+          name: 'Test',
+          instructions: Template.make({
+            source: trim`
+              Test
+              This is the test blueprint.
+            `,
+          }),
+        }),
+      );
+
+      const output = yield* formatSystemPrompt({
+        system: createSystemPrompt({}),
+        blueprints: [blueprint, blueprint],
+        objects: [object, object],
+      });
+
+      console.log(output);
+    }),
+  );
+});

package/src/session/format.ts

@@ -0,0 +1,144 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Array from 'effect/Array';
+import * as Effect from 'effect/Effect';
+import * as Function from 'effect/Function';
+import * as Option from 'effect/Option';
+
+import { Template } from '@dxos/blueprints';
+import { Obj } from '@dxos/echo';
+import { type ObjectId } from '@dxos/echo/internal';
+import { DatabaseService, ObjectVersion } from '@dxos/echo-db';
+import { log } from '@dxos/log';
+import { type ContentBlock, Message } from '@dxos/types';
+import { trim } from '@dxos/util';
+
+import { AiAssistantError } from '../errors';
+
+import { ArtifactDiffResolver } from './artifact-diff';
+import { type AiSessionRunError, type AiSessionRunParams } from './session';
+
+/**
+ * Formats the system prompt.
+ */
+// TODO(burdon): Move to AiPreprocessor.
+export const formatSystemPrompt = ({
+  system,
+  blueprints = [],
+  objects = [],
+}: Pick<AiSessionRunParams<any>, 'system' | 'blueprints' | 'objects'>) =>
+  Effect.gen(function* () {
+    const blueprintDefs = yield* Function.pipe(
+      blueprints,
+      Effect.forEach((blueprint) => Effect.succeed(blueprint.instructions)),
+      Effect.flatMap(Effect.forEach((template) => DatabaseService.loadOption(template.source))),
+      Effect.map(Array.filter(Option.isSome)),
+      Effect.map(
+        Array.map(
+          (template) => trim`
+            <blueprint>
+              ${Template.process(template.value.content)}
+            </blueprint>
+          `,
+        ),
+      ),
+      Effect.map((blueprints) =>
+        blueprints.length > 0 ? ['## Blueprints Definitions', ...blueprints].join('\n\n') : undefined,
+      ),
+    );
+
+    const objectDefs = yield* Function.pipe(
+      objects,
+      Effect.forEach((object) =>
+        Effect.succeed(trim`
+          <object>
+            <dxn>${Obj.getDXN(object)}</dxn>
+            <typename>${Obj.getTypename(object)}</typename>
+          </object>
+        `),
+      ),
+      Effect.map((objects) => (objects.length > 0 ? ['## Context Objects', ...objects].join('\n\n') : undefined)),
+    );
+
+    return yield* Function.pipe(
+      Effect.succeed([system, blueprintDefs, objectDefs].filter((def): def is string => def !== undefined)),
+      Effect.map((parts) => parts.join('\n\n')),
+    );
+  });
+
+/**
+ * Formats the user prompt.
+ */
+// TODO(burdon): Move to AiPreprocessor.
+// TODO(burdon): Convert util below to `Effect.fn` (to preserve stack info)
+export const formatUserPrompt = ({
+  prompt,
+  history = [],
+}: Pick<AiSessionRunParams<any>, 'prompt' | 'history'>): Effect.Effect<Message.Message, AiSessionRunError> =>
+  Effect.gen(function* () {
+    const blocks: ContentBlock.Any[] = [];
+
+    // TODO(dmaretskyi): Evaluate other approaches as `serviceOption` isn't represented in the type system.
+    const artifactDiffResolver = yield* Effect.serviceOption(ArtifactDiffResolver);
+    if (Option.isSome(artifactDiffResolver)) {
+      const versions = gatherObjectVersions(history);
+      const artifactDiff = yield* Effect.tryPromise({
+        try: () =>
+          artifactDiffResolver.value.resolve(
+            [...versions.entries()].map(([id, version]) => ({ id, lastVersion: version })),
+          ),
+        catch: AiAssistantError.wrap({ message: 'Artifact diff resolution error' }),
+      });
+
+      log('version', { artifactDiff, versions });
+      for (const [id, { version }] of [...artifactDiff.entries()]) {
+        if (ObjectVersion.equals(version, versions.get(id)!)) {
+          artifactDiff.delete(id);
+          continue;
+        }
+
+        blocks.push({ _tag: 'anchor', objectId: id, version });
+      }
+
+      if (artifactDiff.size > 0) {
+        blocks.push(createArtifactUpdateBlock(artifactDiff));
+      }
+    }
+
+    return Obj.make(Message.Message, {
+      created: new Date().toISOString(),
+      sender: { role: 'user' },
+      blocks: [...blocks, { _tag: 'text', text: prompt }],
+    });
+  });
+
+const gatherObjectVersions = (messages: Message.Message[]): Map<ObjectId, ObjectVersion> => {
+  const artifactIds = new Map<ObjectId, ObjectVersion>();
+  for (const message of messages) {
+    for (const block of message.blocks) {
+      if (block._tag === 'anchor') {
+        artifactIds.set(block.objectId, block.version as ObjectVersion);
+      }
+    }
+  }
+
+  return artifactIds;
+};
+
+const createArtifactUpdateBlock = (
+  artifactDiff: Map<ObjectId, { version: ObjectVersion; diff?: string }>,
+): ContentBlock.Any => {
+  return {
+    _tag: 'text',
+    // TODO(dmaretskyi): Does this need to be a special content-block?
+    disposition: 'artifact-update',
+    text: trim`
+      The following artifacts have been updated since the last message:
+      ${[...artifactDiff.entries()]
+        .map(([id, { diff }]) => `<changed-artifact id="${id}">${diff ? `\n${diff}` : ''}</changed-artifact>`)
+        .join('\n')}
+    `,
+  };
+};

package/src/session/index.ts

@@ -2,5 +2,10 @@
 // Copyright 2025 DXOS.org
 //
 
+export * from './artifact-diff';
+export * from './observer';
 export * from './session';
+export * from './toolkit';
 export * from './version-pin';
+
+export * as GenericToolkit from './GenericToolkit';

package/src/session/observer.ts

@@ -0,0 +1,59 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Function from 'effect/Function';
+
+import { type AiParser, type ConsolePrinter } from '@dxos/ai';
+import { type Message } from '@dxos/types';
+
+/**
+ * Live observer of the generation process.
+ */
+export interface GenerationObserver extends AiParser.ParseResponseCallbacks {
+  /**
+   * Complete messages fired during the session, both from the model and from the user.
+   * This message will contain all message blocks emitted through the `onBlock` callback.
+   */
+  onMessage: (message: Message.Message) => Effect.Effect<void>;
+}
+
+export const GenerationObserver = Object.freeze({
+  make: ({
+    onBegin = Function.constant(Effect.void),
+    onPart = Function.constant(Effect.void),
+    onBlock = Function.constant(Effect.void),
+    onEnd = Function.constant(Effect.void),
+    onMessage = Function.constant(Effect.void),
+  }: Partial<GenerationObserver> = {}): GenerationObserver => ({
+    onBegin,
+    onPart,
+    onBlock,
+    onEnd,
+    onMessage,
+  }),
+
+  noop: () => GenerationObserver.make(),
+
+  /**
+   * Debug printer to be used in unit-tests and browser devtools.
+   */
+  fromPrinter: (printer: ConsolePrinter) =>
+    GenerationObserver.make({
+      onBlock: (block) =>
+        Effect.sync(() => {
+          if (block.pending) {
+            return; // Only prints full blocks (better for unit-tests and browser devtools).
+          }
+          printer.printContentBlock(block);
+        }),
+      onMessage: (message) =>
+        Effect.sync(() => {
+          if (message.sender.role === 'assistant') {
+            return; // Skip assistant messages since they are printed in the `onBlock` callback.
+          }
+          printer.printMessage(message);
+        }),
+    }),
+});

package/src/session/session.conversations.json

@@ -0,0 +1 @@
+{"conversations":[{"parameters":{"model":"@anthropic/claude-3-5-sonnet-20241022","stream":true,"tools":[]},"prompt":{"content":[{"role":"user","content":"Hello world!","options":{}}]},"response":[{"type":"response-metadata","id":"msg_01Bm496JGgDMgC9YwdYTFFHo","modelId":"claude-3-5-sonnet-20241022","timestamp":"1970-01-01T00:00:00.000Z","metadata":{}},{"type":"text-start","id":"0","metadata":{}},{"type":"text-delta","id":"0","delta":"Hi","metadata":{}},{"type":"text-delta","id":"0","delta":"!","metadata":{}},{"type":"text-delta","id":"0","delta":" How can","metadata":{}},{"type":"text-delta","id":"0","delta":" I help you today?","metadata":{}},{"type":"text-end","id":"0","metadata":{}},{"type":"finish","reason":"stop","usage":{"inputTokens":10,"outputTokens":12,"totalTokens":22},"metadata":{"anthropic":{"usage":{"cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":0},"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"input_tokens":10,"output_tokens":1,"server_tool_use":null,"service_tier":"standard"}}}}]},{"parameters":{"model":"@anthropic/claude-3-5-sonnet-20241022","stream":true,"tools":[{"name":"Calculator","description":"Basic calculator tool","inputSchema":{"type":"object","required":["input"],"properties":{"input":{"type":"string","description":"The calculation to perform."}},"additionalProperties":false}}]},"prompt":{"content":[{"role":"user","content":"What is 10 + 30?","options":{}}]},"response":[{"type":"response-metadata","id":"msg_01UNTbjtTHEpdFgGunu2k8Br","modelId":"claude-3-5-sonnet-20241022","timestamp":"1970-01-01T00:00:00.000Z","metadata":{}},{"type":"text-start","id":"0","metadata":{}},{"type":"text-delta","id":"0","delta":"I","metadata":{}},{"type":"text-delta","id":"0","delta":"'ll help","metadata":{}},{"type":"text-delta","id":"0","delta":" you calculate","metadata":{}},{"type":"text-delta","id":"0","delta":" ","metadata":{}},{"type":"text-delta","id":"0","delta":"10 + 30","metadata":{}},{"type":"text-delta","id":"0","delta":" using the","metadata":{}},{"type":"text-delta","id":"0","delta":" Calculator tool.","metadata":{}},{"type":"text-end","id":"0","metadata":{}},{"type":"tool-params-start","id":"toolu_01LTGUgfihCQtVchm1b37xHQ","name":"Calculator","providerExecuted":false,"metadata":{}},{"type":"tool-params-delta","id":"toolu_01LTGUgfihCQtVchm1b37xHQ","delta":"","metadata":{}},{"type":"tool-params-delta","id":"toolu_01LTGUgfihCQtVchm1b37xHQ","delta":"{\"input\": \"","metadata":{}},{"type":"tool-params-delta","id":"toolu_01LTGUgfihCQtVchm1b37xHQ","delta":"10 + 30","metadata":{}},{"type":"tool-params-delta","id":"toolu_01LTGUgfihCQtVchm1b37xHQ","delta":"\"}","metadata":{}},{"type":"tool-params-end","id":"toolu_01LTGUgfihCQtVchm1b37xHQ","metadata":{}},{"type":"tool-call","id":"toolu_01LTGUgfihCQtVchm1b37xHQ","name":"Calculator","params":{"input":"10 + 30"},"providerExecuted":false,"metadata":{}},{"type":"finish","reason":"tool-calls","usage":{"inputTokens":394,"outputTokens":73,"totalTokens":467},"metadata":{"anthropic":{"usage":{"cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":0},"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"input_tokens":394,"output_tokens":1,"server_tool_use":null,"service_tier":"standard"}}}}]},{"parameters":{"model":"@anthropic/claude-3-5-sonnet-20241022","stream":true,"tools":[{"name":"Calculator","description":"Basic calculator tool","inputSchema":{"type":"object","required":["input"],"properties":{"input":{"type":"string","description":"The calculation to perform."}},"additionalProperties":false}}]},"prompt":{"content":[{"role":"user","content":"What is 10 + 30?","options":{}},{"role":"assistant","content":[{"type":"text","text":"I'll help you calculate 10 + 30 using the Calculator tool.","options":{}},{"type":"tool-call","id":"toolu_01LTGUgfihCQtVchm1b37xHQ","name":"Calculator","params":{"input":"10 + 30"},"providerExecuted":false,"options":{}}],"options":{}},{"role":"tool","content":[{"type":"tool-result","id":"toolu_01LTGUgfihCQtVchm1b37xHQ","name":"Calculator","result":{"result":40},"options":{}}],"options":{}}]},"response":[{"type":"response-metadata","id":"msg_01AKio3GheJGn38BhvAp33rs","modelId":"claude-3-5-sonnet-20241022","timestamp":"1970-01-01T00:00:00.000Z","metadata":{}},{"type":"text-start","id":"0","metadata":{}},{"type":"text-delta","id":"0","delta":"The result","metadata":{}},{"type":"text-delta","id":"0","delta":" of 10 +","metadata":{}},{"type":"text-delta","id":"0","delta":" 30 is ","metadata":{}},{"type":"text-delta","id":"0","delta":"40.","metadata":{}},{"type":"text-end","id":"0","metadata":{}},{"type":"finish","reason":"stop","usage":{"inputTokens":482,"outputTokens":18,"totalTokens":500},"metadata":{"anthropic":{"usage":{"cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":0},"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"input_tokens":482,"output_tokens":3,"server_tool_use":null,"service_tier":"standard"}}}}]}]}