@dxos/assistant 0.8.4-main.dedc0f3 → 0.8.4-main.dfabb4ec29

package/src/extraction/quotes.ts

@@ -2,11 +2,10 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema } from 'effect';
+import * as Schema from 'effect/Schema';
 
-import { Filter, Query } from '@dxos/echo';
-import { type EchoDatabase } from '@dxos/echo-db';
-import { ObjectId } from '@dxos/echo-schema';
+import { type Database, Filter, Query } from '@dxos/echo';
+import { ObjectId } from '@dxos/keys';
 import { DXN } from '@dxos/keys';
 import { log } from '@dxos/log';
 
@@ -28,10 +27,10 @@ export const ReferencedQuotes = Schema.Struct({
 });
 export type ReferencedQuotes = Schema.Schema.Type<typeof ReferencedQuotes>;
 
-export const findQuotes = async (quotes: string[], db: EchoDatabase): Promise<ReferencedQuotes> => {
+export const findQuotes = async (quotes: string[], db: Database.Database): Promise<ReferencedQuotes> => {
   const references = await Promise.all(
     quotes.map(async (quote) => {
-      const { objects } = await db.query(Query.select(Filter.text(quote, { type: 'vector' }))).run();
+      const objects = await db.query(Query.select(Filter.text(quote, { type: 'vector' }))).run();
       log.info('found quotes in vector index', { objects, quote });
       return objects.length > 0 ? [{ id: objects[0].id.toString(), quote }] : [];
     }),
@@ -51,7 +50,7 @@ export const insertReferences = (text: string, quotes: ReferencedQuotes) => {
 
     // Use a case-insensitive regular expression to replace the quote.
     const regex = new RegExp(quote.quote.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi');
-    text = text.replace(regex, `[${quote.quote}][${DXN.fromLocalObjectId(quote.id).toString()}]`);
+    text = text.replace(regex, `[${quote.quote}](${DXN.fromLocalObjectId(quote.id).toString()})`);
   }
 
   return text;

package/src/functions/services.ts

@@ -2,97 +2,149 @@
 // Copyright 2025 DXOS.org
 //
 
-import { AiTool, type AiToolkit } from '@effect/ai';
-import { Context, Effect, Layer, Record, Schema } from 'effect';
+import * as Tool from '@effect/ai/Tool';
+import type * as Toolkit from '@effect/ai/Toolkit';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+import * as Record from 'effect/Record';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
 
 import { AiToolNotFoundError, ToolExecutionService, ToolResolverService } from '@dxos/ai';
+import { OpaqueToolkit } from '@dxos/ai';
+import { Operation, OperationRegistry } from '@dxos/compute';
 import { todo } from '@dxos/debug';
-import { type FunctionDefinition, LocalFunctionExecutionService } from '@dxos/functions';
+import { Ref } from '@dxos/echo';
 import { invariant } from '@dxos/invariant';
 
-export const makeToolResolverFromFunctions = (
-  functions: FunctionDefinition<any, any>[],
-  toolkit: AiToolkit.Any,
-): Layer.Layer<ToolResolverService> => {
-  return Layer.succeed(ToolResolverService, {
-    resolve: Effect.fn('resolveTool')(function* (id) {
-      const tool = toolkit.tools[id];
-      if (tool) {
-        return tool;
-      }
-
-      const functionDef = functions.find((fn) => fn.name === id);
-      if (!functionDef) {
-        return yield* Effect.fail(new AiToolNotFoundError(id));
-      }
-
-      return projectFunctionToTool(functionDef);
+import { RefFromLLM } from '../types';
+
+export const makeToolResolverFromOperations = <R = never>({
+  toolkit: extraToolkit = OpaqueToolkit.empty,
+}: { toolkit?: OpaqueToolkit.OpaqueToolkit<never, never, R> } = {}): Layer.Layer<
+  ToolResolverService,
+  never,
+  OpaqueToolkit.OpaqueToolkitProvider | OperationRegistry.Service | R
+> => {
+  return Layer.effect(
+    ToolResolverService,
+    Effect.gen(function* () {
+      const toolkitProvider = yield* OpaqueToolkit.OpaqueToolkitProvider;
+      const operationRegistry = yield* OperationRegistry.Service;
+      return {
+        resolve: (id): Effect.Effect<Tool.Any, AiToolNotFoundError> =>
+          Effect.gen(function* () {
+            const toolkit = OpaqueToolkit.merge(extraToolkit, toolkitProvider.getToolkit());
+
+            const tool = toolkit.toolkit.tools[id];
+            if (tool) {
+              return tool;
+            }
+
+            return yield* operationRegistry.resolve(id).pipe(
+              Effect.flatMap(
+                Option.match({
+                  onSome: (_) => Effect.succeed(projectFunctionToTool(_)),
+                  onNone: () => Effect.fail(new AiToolNotFoundError(id)),
+                }),
+              ),
+            );
+          }),
+      } satisfies Context.Tag.Service<ToolResolverService>;
     }),
-  });
+  );
 };
 
-export const makeToolExecutionServiceFromFunctions = (
-  functions: FunctionDefinition<any, any>[],
-  toolkit: AiToolkit.AiToolkit<AiTool.Any>,
-  handlersLayer: Layer.Layer<AiTool.ToHandler<AiTool.AiTool<any>>, never, never>,
-): Layer.Layer<ToolExecutionService, never, LocalFunctionExecutionService> => {
-  return Layer.effect(
+export const makeToolExecutionService = <E, R>(opts: {
+  invoke: (tool: Tool.Any, input: unknown) => Effect.Effect<unknown>;
+}): Layer.Layer<ToolExecutionService, never, OpaqueToolkit.OpaqueToolkitProvider> =>
+  Layer.effect(
     ToolExecutionService,
     Effect.gen(function* () {
-      const toolkitHandler = yield* toolkit.pipe(Effect.provide(handlersLayer));
-      const localFunctionExecutionService = yield* LocalFunctionExecutionService;
+      const toolkitProvider = yield* OpaqueToolkit.OpaqueToolkitProvider;
+      const toolkit = toolkitProvider.getToolkit();
+
+      const toolkitHandler = yield* toolkit.toolkit.pipe(Effect.provide(toolkit.layer));
+      invariant(isHandlerLike(toolkitHandler));
 
       return {
         handlersFor: (toolkit) => {
-          const makeHandler = (tool: AiTool.Any): ((params: unknown) => Effect.Effect<unknown, any, any>) => {
-            return Effect.fn('toolFunctionHandler')(function* (input: any) {
-              if (toolkitHandler.tools.find((t: AiTool.Any) => t.name === tool.name)) {
-                // TODO(wittjosiah): Everything is `never` here.
-                return yield* (toolkitHandler.handle as any)(tool.name, input);
-              }
+          const makeHandler = (tool: Tool.Any): ((params: unknown) => Effect.Effect<unknown, any, any>) => {
+            return Effect.fn(`toolFunctionHandler ${tool.name}`)(function* (input: any) {
+              if (toolkitHandler.tools[tool.name]) {
+                if (Tool.isProviderDefined(tool)) {
+                  throw new Error('Attempted to call a provider-defined tool');
+                }
 
-              const { functionName } = Context.get(FunctionToolAnnotation)(tool.annotations as any);
-              const functionDef = functions.find((fn) => fn.name === functionName);
-              if (!functionDef) {
-                return yield* Effect.fail(new AiToolNotFoundError(tool.name));
+                // TODO(wittjosiah): Everything is `never` here.
+                const { result } = yield* (toolkitHandler.handle as any)(tool.name, input);
+                return result;
               }
 
-              return yield* localFunctionExecutionService
-                .invokeFunction(functionDef, input)
-                .pipe(Effect.catchAllDefect((defect) => Effect.fail(defect)));
+              return yield* opts.invoke(tool, input).pipe(Effect.catchAllDefect((defect) => Effect.fail(defect)));
             });
           };
 
-          return toolkit.of(Record.map(toolkit.tools, (tool, _name) => makeHandler(tool)) as any) as any;
+          return toolkit.of(
+            Record.map(toolkit.tools, (tool, _name) => (Tool.isUserDefined(tool) ? makeHandler(tool) : null)) as any,
+          ) as any;
         },
       };
     }),
   );
+
+export const makeToolExecutionServiceFromOperationInvoker = (): Layer.Layer<
+  ToolExecutionService,
+  never,
+  Operation.Service | OpaqueToolkit.OpaqueToolkitProvider
+> => {
+  return Layer.unwrapEffect(
+    Effect.gen(function* () {
+      const operationInvoker = yield* Operation.Service;
+
+      return makeToolExecutionService({
+        invoke: (tool, input) =>
+          Effect.gen(function* () {
+            const operationDef = getOperationFromTool(tool).pipe(Option.getOrThrow);
+
+            return yield* operationInvoker.invoke(operationDef, input).pipe(Effect.orDie);
+          }),
+      });
+    }),
+  );
 };
 
-/**
- * Tools that are projected from functions have this annotation.
- */
-class FunctionToolAnnotation extends Context.Tag('@dxos/assisatnt/FunctionToolAnnotation')<
+export const ToolExecutionServices = Layer.mergeAll(
+  makeToolResolverFromOperations(),
+  makeToolExecutionServiceFromOperationInvoker(),
+);
+
+class FunctionToolAnnotation extends Context.Tag('@dxos/assistant/FunctionToolAnnotation')<
   FunctionToolAnnotation,
-  {
-    functionName: string;
-  }
+  { definition: Operation.Definition.Any }
 >() {}
 
-const toolCache = new WeakMap<FunctionDefinition<any, any>, AiTool.Any>();
+export const getOperationFromTool = (tool: Tool.Any): Option.Option<Operation.Definition.Any> => {
+  return Context.getOption(FunctionToolAnnotation)(tool.annotations).pipe(Option.map(({ definition }) => definition));
+};
+
+const toolCache = new WeakMap<Operation.Definition.Any, Tool.Any>();
 
-const projectFunctionToTool = (fn: FunctionDefinition<any, any>): AiTool.Any => {
+/**
+ * Projects an `Operation.Definition` into an `AiTool`.
+ */
+const projectFunctionToTool = (fn: Operation.Definition.Any): Tool.Any => {
   if (toolCache.has(fn)) {
     return toolCache.get(fn)!;
   }
 
-  const tool = AiTool.make(makeToolName(fn.name), {
-    description: fn.description,
-    parameters: createStructFieldsFromSchema(fn.inputSchema),
-    // TODO(dmaretskyi): Include output schema.
-    failure: Schema.Any, // TODO(dmaretskyi): Better type for the failure?
-  }).annotate(FunctionToolAnnotation, { functionName: fn.name });
+  const tool = Tool.make(makeToolName(fn.meta.name ?? fn.meta.key), {
+    description: fn.meta.description,
+    parameters: createStructFieldsFromSchema(fn.input),
+    failure: Schema.Any,
+  }).annotate(FunctionToolAnnotation, { definition: fn });
   toolCache.set(fn, tool);
   return tool;
 };
@@ -101,8 +153,8 @@ const projectFunctionToTool = (fn: FunctionDefinition<any, any>): AiTool.Any =>
  * @returns Tool name produced from function name by escaping invalid characters.
  */
 const makeToolName = (name: string) => {
-  const toolName = name.replace(/[^a-zA-Z0-9]/g, '_');
-  invariant(toolName.match(/^[a-zA-Z_][a-zA-Z0-9-_]*$/));
+  const toolName = name.toLowerCase().replace(/[^a-zA-Z0-9]/g, '-');
+  invariant(toolName.match(/^[a-z_][a-z0-9-_]*$/));
   return toolName;
 };
 
@@ -110,10 +162,53 @@ const makeToolName = (name: string) => {
 const createStructFieldsFromSchema = (schema: Schema.Schema<any, any>): Record<string, Schema.Schema<any, any>> => {
   switch (schema.ast._tag) {
     case 'TypeLiteral':
-      return Object.fromEntries(schema.ast.propertySignatures.map((prop) => [prop.name, Schema.make(prop.type)]));
+      return Object.fromEntries(
+        schema.ast.propertySignatures.map((prop) => [prop.name, Schema.make(mapSchemaTypeForLLM(prop.type))]),
+      );
     case 'VoidKeyword':
       return {};
     default:
       return todo(`Unsupported schema AST: ${schema.ast._tag}`);
   }
 };
+
+/**
+ * Picks an LLM-friendly schema type for the given schema AST.
+ * The picked schema type decodes to the original schema type.
+ */
+const mapSchemaTypeForLLM = (ast: SchemaAST.AST): SchemaAST.AST => {
+  if (Ref.isRefType(ast)) {
+    const description = ast.annotations.description
+      ? ast.annotations.description + '\n' + RefFromLLM.ast.annotations.description
+      : (RefFromLLM.ast.annotations.description as string);
+    return RefFromLLM.annotations({ description }).ast;
+  } else if (SchemaAST.isTupleType(ast)) {
+    return new SchemaAST.TupleType(
+      ast.elements.map((t) => new SchemaAST.OptionalType(mapSchemaTypeForLLM(t.type), t.isOptional, t.annotations)),
+      ast.rest.map((t) => new SchemaAST.Type(mapSchemaTypeForLLM(t.type), t.annotations)),
+      ast.isReadonly,
+      ast.annotations,
+    );
+  } else if (SchemaAST.isTypeLiteral(ast)) {
+    return new SchemaAST.TypeLiteral(
+      ast.propertySignatures.map(
+        (p) =>
+          new SchemaAST.PropertySignature(
+            p.name,
+            mapSchemaTypeForLLM(p.type),
+            p.isOptional,
+            p.isReadonly,
+            p.annotations,
+          ),
+      ),
+      ast.indexSignatures,
+      ast.annotations,
+    );
+  }
+
+  return ast;
+};
+
+const isHandlerLike = (value: unknown): value is Toolkit.WithHandler<Record<string, Tool.Any>> => {
+  return typeof (value as any).tools === 'object' && typeof (value as any).handle === 'function';
+};

package/src/index.ts

@@ -4,8 +4,10 @@
 
 export * from './conversation';
 export * from './diff';
+export * from './errors';
+export * from './execution-graph';
 export * from './functions';
 export * from './session';
 export * from './templates';
 export * from './types';
-export * from './errors';
+export * from './tracing';

package/src/session/artifact-diff.ts

@@ -2,10 +2,10 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Context } from 'effect';
+import * as Context from 'effect/Context';
 
 import { type ObjectVersion } from '@dxos/echo-db';
-import { type ObjectId } from '@dxos/echo-schema';
+import { type ObjectId } from '@dxos/keys';
 
 /**
  * Resolves artifact ids to their versions.

package/src/session/error-handling.ts

@@ -2,11 +2,12 @@
 // Copyright 2025 DXOS.org
 //
 
-import { AiError } from '@effect/ai';
-import { HttpClientError } from '@effect/platform';
-import { Effect, Schema } from 'effect';
+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 { AnthropicError } from '../errors';
+import { AiModelError } from '../errors';
 
 const AnthropicErrorResponse = Schema.Struct({
   type: Schema.Literal('error'),
@@ -16,6 +17,7 @@ const AnthropicErrorResponse = Schema.Struct({
   }),
 });
 
+// TODO(dmaretskyi): Needs rework
 export const mapAiError = (err: AiError.AiError): Effect.Effect<AiError.AiError> =>
   Effect.gen(function* () {
     const cause = err.cause;
@@ -24,8 +26,11 @@ export const mapAiError = (err: AiError.AiError): Effect.Effect<AiError.AiError>
         Effect.flatMap(Schema.decodeUnknown(AnthropicErrorResponse, { exact: false })),
       );
 
-      const parsedCause = new AnthropicError(`${body.error.type}: ${body.error.message}`);
-      return new AiError.AiError({
+      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,

package/src/session/format.ts

@@ -2,21 +2,22 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Array, Effect, Option, pipe } from 'effect';
+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 FunctionNotFoundError, type Operation, type OperationRegistry, Template } from '@dxos/compute';
+import { type Database, Obj } from '@dxos/echo';
 import { ObjectVersion } from '@dxos/echo-db';
-import { type ObjectId } from '@dxos/echo-schema';
-import { DatabaseService } from '@dxos/functions';
+import type { ObjectNotFoundError } from '@dxos/echo/Err';
+import { type ObjectId } from '@dxos/keys';
 import { log } from '@dxos/log';
-import { type ContentBlock, DataType } from '@dxos/schema';
+import { type ContentBlock, Message } from '@dxos/types';
 import { trim } from '@dxos/util';
 
 import { AiAssistantError } from '../errors';
-
 import { ArtifactDiffResolver } from './artifact-diff';
-import { type AiSessionRunParams } from './session';
+import { type AiRequestRunError, type AiRequestRunProps } from './request';
 
 /**
  * Formats the system prompt.
@@ -26,20 +27,24 @@ export const formatSystemPrompt = ({
   system,
   blueprints = [],
   objects = [],
-}: Pick<AiSessionRunParams<any>, 'system' | 'blueprints' | 'objects'>) =>
+}: Pick<AiRequestRunProps, 'system' | 'blueprints' | 'objects'>): Effect.Effect<
+  string,
+  FunctionNotFoundError | ObjectNotFoundError,
+  Database.Service | OperationRegistry.Service | Operation.Service
+> =>
   Effect.gen(function* () {
-    const blueprintDefs = yield* pipe(
+    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`
+      Effect.flatMap(
+        Effect.forEach((template) =>
+          Effect.gen(function* () {
+            return trim`
             <blueprint>
-              ${Template.process(template.value.content)}
+              ${yield* Template.processTemplate(template)}
             </blueprint>
-          `,
+          `;
+          }),
         ),
       ),
       Effect.map((blueprints) =>
@@ -47,7 +52,7 @@ export const formatSystemPrompt = ({
       ),
     );
 
-    const objectDefs = yield* pipe(
+    const objectDefs = yield* Function.pipe(
       objects,
       Effect.forEach((object) =>
         Effect.succeed(trim`
@@ -60,18 +65,21 @@ export const formatSystemPrompt = ({
       Effect.map((objects) => (objects.length > 0 ? ['## Context Objects', ...objects].join('\n\n') : undefined)),
     );
 
-    return yield* pipe(
+    return yield* Function.pipe(
       Effect.succeed([system, blueprintDefs, objectDefs].filter((def): def is string => def !== undefined)),
       Effect.map((parts) => parts.join('\n\n')),
     );
-  });
+  }).pipe(Effect.withSpan('formatSystemPrompt'));
 
 /**
  * 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'>) =>
+export const formatUserPrompt = ({
+  prompt,
+  history = [],
+}: Pick<AiRequestRunProps, 'prompt' | 'history'>): Effect.Effect<Message.Message, AiRequestRunError> =>
   Effect.gen(function* () {
     const blocks: ContentBlock.Any[] = [];
 
@@ -84,7 +92,7 @@ export const formatUserPrompt = ({ prompt, history = [] }: Pick<AiSessionRunPara
           artifactDiffResolver.value.resolve(
             [...versions.entries()].map(([id, version]) => ({ id, lastVersion: version })),
           ),
-        catch: AiAssistantError.wrap('Artifact diff resolution error'),
+        catch: AiAssistantError.wrap({ message: 'Artifact diff resolution error' }),
       });
 
       log('version', { artifactDiff, versions });
@@ -102,14 +110,14 @@ export const formatUserPrompt = ({ prompt, history = [] }: Pick<AiSessionRunPara
       }
     }
 
-    return Obj.make(DataType.Message, {
+    return Obj.make(Message.Message, {
       created: new Date().toISOString(),
       sender: { role: 'user' },
-      blocks: [...blocks, { _tag: 'text', text: prompt }],
+      blocks: typeof prompt === 'string' ? [...blocks, { _tag: 'text', text: prompt }] : [...blocks, ...prompt],
     });
-  });
+  }).pipe(Effect.withSpan('formatUserPrompt'));
 
-const gatherObjectVersions = (messages: DataType.Message[]): Map<ObjectId, ObjectVersion> => {
+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) {
@@ -128,7 +136,7 @@ const createArtifactUpdateBlock = (
   return {
     _tag: 'text',
     // TODO(dmaretskyi): Does this need to be a special content-block?
-    disposition: 'artifact-update',
+    disposition: 'synthetic',
     text: trim`
       The following artifacts have been updated since the last message:
       ${[...artifactDiff.entries()]

package/src/session/index.ts

@@ -4,6 +4,7 @@
 
 export * from './artifact-diff';
 export * from './observer';
-export * from './session';
+export * from './request';
 export * from './toolkit';
 export * from './version-pin';
+export * from './format';

package/src/session/observer.ts

@@ -2,20 +2,24 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Effect, Function } from 'effect';
+import type * as Tool from '@effect/ai/Tool';
+import * as Effect from 'effect/Effect';
+import * as Function from 'effect/Function';
 
 import { type AiParser, type ConsolePrinter } from '@dxos/ai';
-import { type DataType } from '@dxos/schema';
+import { type Message } from '@dxos/types';
 
 /**
  * Live observer of the generation process.
  */
-export interface GenerationObserver extends AiParser.ParseResponseCallbacks {
+export interface GenerationObserver<
+  Tools extends Record<string, Tool.Any> = any,
+> extends AiParser.ParseResponseCallbacks<Tools> {
   /**
    * 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: DataType.Message) => Effect.Effect<void>;
+  onMessage: (message: Message.Message) => Effect.Effect<void>;
 }
 
 export const GenerationObserver = Object.freeze({