@dxos/assistant 0.8.4-main.b97322e → 0.8.4-main.bcb3aa67d6

package/src/extraction/quotes.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { describe, test, expect } from 'vitest';
+import { describe, expect, test } from 'vitest';
 
 import { insertReferences } from './quotes';
 
@@ -13,7 +13,7 @@ describe('insertReferences', () => {
     };
 
     expect(insertReferences('This is a computational irreducibility test.', quotes)).toBe(
-      'This is a [computational irreducibility][dxn:echo:@:01JTG9JW11XGWJZ32AW8ET93D1] test.',
+      'This is a [computational irreducibility](dxn:echo:@:01JTG9JW11XGWJZ32AW8ET93D1) test.',
     );
     expect(
       insertReferences(
@@ -21,7 +21,7 @@ describe('insertReferences', () => {
         quotes,
       ),
     ).toBe(
-      "And what I'd like to talk today about is Steven Wolfram's concept of a [computational irreducibility][dxn:echo:@:01JTG9JW11XGWJZ32AW8ET93D1].",
+      "And what I'd like to talk today about is Steven Wolfram's concept of a [computational irreducibility](dxn:echo:@:01JTG9JW11XGWJZ32AW8ET93D1).",
     );
   });
 });

package/src/extraction/quotes.ts

@@ -2,11 +2,10 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema } from 'effect';
+import * as Schema from 'effect/Schema';
 
-import { Query, Filter } 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,72 +2,264 @@
 // Copyright 2025 DXOS.org
 //
 
-import { AiTool } from '@effect/ai';
-import { Context, Effect, Layer, Match, Predicate, 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 Record from 'effect/Record';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
 
 import { AiToolNotFoundError, ToolExecutionService, ToolResolverService } from '@dxos/ai';
+import { GenericToolkit } from '@dxos/ai';
 import { todo } from '@dxos/debug';
-import { FunctionError, type FunctionContext, type FunctionDefinition, type Services } from '@dxos/functions';
+import { Ref } from '@dxos/echo';
+import { FunctionInvocationService, FunctionNotFoundError } from '@dxos/functions';
 import { invariant } from '@dxos/invariant';
+import { Operation, OperationRegistry } from '@dxos/operation';
+import * as Option from 'effect/Option';
 
-export const makeToolResolverFromFunctions = (
-  functions: FunctionDefinition<any, any>[],
-): Layer.Layer<ToolResolverService> => {
-  return Layer.succeed(ToolResolverService, {
-    resolve: Effect.fn('resolveTool')(function* (id) {
-      const fn = functions.find((f) => f.name === id);
-      if (!fn) {
-        return yield* Effect.fail(new AiToolNotFoundError(id));
-      }
-
-      return projectFunctionToTool(fn);
+import { RefFromLLM } from '../types';
+
+/**
+ * Constructs a `ToolResolverService` whose `resolve(id)` looks up tools in the following order:
+ *  1. Toolkit: return an existing tool from the provided `toolkit` if one is present under `id`.
+ *  2. Operations in DB: query by `key=id`; if found, deserialize and project to a tool.
+ *  3. Registered operations: fall back to a matching `Operation.Definition` from the handler set.
+ *
+ * If none of the above yield a match, the effect fails with `AiToolNotFoundError`.
+ *
+ * Requires `Database.Service` in the environment.
+ *
+ * @deprecated Moving to operation-based services.
+ */
+export const makeToolResolverFromFunctions = (): Layer.Layer<
+  ToolResolverService,
+  never,
+  GenericToolkit.GenericToolkitProvider | FunctionInvocationService
+> => {
+  return Layer.effect(
+    ToolResolverService,
+    Effect.gen(function* () {
+      const toolkitProvider = yield* GenericToolkit.GenericToolkitProvider;
+      const functionInvocationService = yield* FunctionInvocationService;
+      return {
+        resolve: (id): Effect.Effect<Tool.Any, AiToolNotFoundError> =>
+          Effect.gen(function* () {
+            const toolkit = toolkitProvider.getToolkit();
+
+            const tool = toolkit.toolkit.tools[id];
+            if (tool) {
+              return tool;
+            }
+
+            return yield* functionInvocationService.resolveFunction(id).pipe(
+              Effect.map(projectFunctionToTool),
+              Effect.catchTag('FunctionNotFound', () => Effect.fail(new AiToolNotFoundError(id))),
+            );
+          }),
+      } satisfies Context.Tag.Service<ToolResolverService>;
     }),
-  });
+  );
 };
 
-export const makeToolExecutionServiceFromFunctions = (
-  functions: FunctionDefinition<any, any>[],
-): Layer.Layer<ToolExecutionService> => {
-  return Layer.succeed(ToolExecutionService, {
-    handlersFor: (toolkit) => {
-      const makeHandler = (tool: AiTool.Any): ((params: unknown) => Effect.Effect<unknown, any, any>) => {
-        return Effect.fn('toolFunctionHandler')(function* (input: any) {
-          const { functionName } = Context.get(FunctionToolAnnotation)(tool.annotations as any);
-          const fnDef = functions.find((f) => f.name === functionName);
-          if (!fnDef) {
-            return yield* Effect.fail(new AiToolNotFoundError(tool.name));
-          }
-
-          return yield* invokeFunction(fnDef, input).pipe(Effect.catchAllDefect((defect) => Effect.fail(defect)));
-        });
+/**
+ * @deprecated Moving to operation-based services.
+ */
+export const makeToolExecutionServiceFromFunctions = (): Layer.Layer<
+  ToolExecutionService,
+  never,
+  FunctionInvocationService | GenericToolkit.GenericToolkitProvider
+> => {
+  return Layer.effect(
+    ToolExecutionService,
+    Effect.gen(function* () {
+      const toolkitProvider = yield* GenericToolkit.GenericToolkitProvider;
+      const toolkit = toolkitProvider.getToolkit();
+
+      const toolkitHandler = yield* toolkit.toolkit.pipe(Effect.provide(toolkit.layer));
+      invariant(isHandlerLike(toolkitHandler));
+      const functionInvocationService = yield* FunctionInvocationService;
+
+      return {
+        handlersFor: (toolkit) => {
+          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');
+                }
+
+                // TODO(wittjosiah): Everything is `never` here.
+                const { result } = yield* (toolkitHandler.handle as any)(tool.name, input);
+                return result;
+              }
+
+              const functionDef = getOperationFromTool(tool).pipe(Option.getOrThrow);
+
+              return yield* functionInvocationService
+                .invokeFunction(functionDef, input as any)
+                .pipe(Effect.catchAllDefect((defect) => Effect.fail(defect)));
+            });
+          };
+
+          return toolkit.of(
+            Record.map(toolkit.tools, (tool, _name) => (Tool.isUserDefined(tool) ? makeHandler(tool) : null)) as any,
+          ) as any;
+        },
       };
+    }),
+  );
+};
+
+export const makeToolResolverFromOperations = <R = never>({
+  toolkit: extraToolkit = GenericToolkit.empty,
+}: { toolkit?: GenericToolkit.GenericToolkit<never, never, R> } = {}): Layer.Layer<
+  ToolResolverService,
+  never,
+  GenericToolkit.GenericToolkitProvider | OperationRegistry.Service | R
+> => {
+  return Layer.effect(
+    ToolResolverService,
+    Effect.gen(function* () {
+      const toolkitProvider = yield* GenericToolkit.GenericToolkitProvider;
+      const operationRegistry = yield* OperationRegistry.Service;
+      return {
+        resolve: (id): Effect.Effect<Tool.Any, AiToolNotFoundError> =>
+          Effect.gen(function* () {
+            const toolkit = GenericToolkit.merge(extraToolkit, toolkitProvider.getToolkit());
+
+            const tool = toolkit.toolkit.tools[id];
+            if (tool) {
+              return tool;
+            }
 
-      return toolkit.of(Record.map(toolkit.tools, (tool, name) => makeHandler(tool)) as any) as any;
-    },
-  });
+            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 makeToolExecutionService = <E, R>(opts: {
+  invoke: (tool: Tool.Any, input: unknown) => Effect.Effect<unknown>;
+}): Layer.Layer<ToolExecutionService, never, GenericToolkit.GenericToolkitProvider> =>
+  Layer.effect(
+    ToolExecutionService,
+    Effect.gen(function* () {
+      const toolkitProvider = yield* GenericToolkit.GenericToolkitProvider;
+      const toolkit = toolkitProvider.getToolkit();
+
+      const toolkitHandler = yield* toolkit.toolkit.pipe(Effect.provide(toolkit.layer));
+      invariant(isHandlerLike(toolkitHandler));
+
+      return {
+        handlersFor: (toolkit) => {
+          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');
+                }
+
+                // TODO(wittjosiah): Everything is `never` here.
+                const { result } = yield* (toolkitHandler.handle as any)(tool.name, input);
+                return result;
+              }
+
+              return yield* opts.invoke(tool, input).pipe(Effect.catchAllDefect((defect) => Effect.fail(defect)));
+            });
+          };
+
+          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 | GenericToolkit.GenericToolkitProvider
+> => {
+  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.
+ * @deprecated Bridge beetwen deprecated function invocataion service and operation services until we remove function invocation service.
  */
-class FunctionToolAnnotation extends Context.Tag('@dxos/assisatnt/FunctionToolAnnotation')<
+export const functionInvocationServiceFromOperations: Layer.Layer<
+  FunctionInvocationService,
+  never,
+  OperationRegistry.Service | Operation.Service
+> = Layer.effect(
+  FunctionInvocationService,
+  Effect.gen(function* () {
+    const operationRegistry = yield* OperationRegistry.Service;
+    const operationInvoker = yield* Operation.Service;
+    return {
+      invokeFunction: (operationDef, input) => operationInvoker.invoke(operationDef, input).pipe(Effect.orDie),
+      resolveFunction: (key) =>
+        operationRegistry.resolve(key).pipe(
+          Effect.flatten,
+          Effect.catchTag('NoSuchElementException', () => Effect.fail(new FunctionNotFoundError(key))),
+        ),
+    } satisfies Context.Tag.Service<FunctionInvocationService>;
+  }),
+);
+
+export const ToolExecutionServices = Layer.mergeAll(
+  makeToolResolverFromFunctions(),
+  makeToolExecutionServiceFromFunctions(),
+);
+
+class FunctionToolAnnotation extends Context.Tag('@dxos/assistant/FunctionToolAnnotation')<
   FunctionToolAnnotation,
-  {
-    functionName: string;
-  }
+  { definition: Operation.Definition.Any }
 >() {}
 
-const toolCache = new WeakMap<FunctionDefinition<any, any>, AiTool.Any>();
-const projectFunctionToTool = (fn: 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>();
+
+/**
+ * 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;
 };
@@ -76,64 +268,62 @@ 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;
 };
 
 // TODO(dmaretskyi): Factor out.
 const createStructFieldsFromSchema = (schema: Schema.Schema<any, any>): Record<string, Schema.Schema<any, any>> => {
-  return Match.value(schema.ast).pipe(
-    Match.when(Predicate.isTagged('TypeLiteral'), (ast) => {
-      return Object.fromEntries(ast.propertySignatures.map((prop) => [prop.name, Schema.make(prop.type)]));
-    }),
-    Match.orElseAbsurd,
-  );
+  switch (schema.ast._tag) {
+    case 'TypeLiteral':
+      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}`);
+  }
 };
 
-// TODO(dmaretskyi): Factor out.
-const invokeFunction = (fnDef: FunctionDefinition<any, any>, input: any): Effect.Effect<unknown, never, Services> =>
-  Effect.gen(function* () {
-    // Assert input matches schema
-    const assertInput = fnDef.inputSchema.pipe(Schema.asserts);
-    (assertInput as any)(input);
-
-    const context: FunctionContext = {
-      getService: () => todo(),
-      getSpace: async (_spaceId: any) => {
-        throw new Error('Not available. Use the database service instead.');
-      },
-      space: undefined,
-      get ai(): never {
-        throw new Error('Not available. Use the ai service instead.');
-      },
-    };
-
-    // TODO(dmaretskyi): This should be delegated to a function invoker service.
-    const data = yield* Effect.gen(function* () {
-      const result = fnDef.handler({ context, data: input });
-      if (Effect.isEffect(result)) {
-        return yield* (result as Effect.Effect<unknown, unknown, Services>).pipe(Effect.orDie);
-      } else if (
-        typeof result === 'object' &&
-        result !== null &&
-        'then' in result &&
-        typeof result.then === 'function'
-      ) {
-        return yield* Effect.promise(() => result);
-      } else {
-        return result;
-      }
-    }).pipe(
-      Effect.orDie,
-      Effect.catchAllDefect((defect) =>
-        Effect.die(new FunctionError('Error running function', { context: { name: fnDef.name }, cause: defect })),
+/**
+ * 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,
     );
+  }
 
-    // Assert output matches schema
-    const assertOutput = fnDef.outputSchema?.pipe(Schema.asserts);
-    (assertOutput as any)(data);
+  return ast;
+};
 
-    return data;
-  }).pipe(Effect.withSpan('invokeFunction', { attributes: { name: fnDef.name } }));
+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/functions.conversations.json

@@ -0,0 +1 @@
+{"conversations":[{"parameters":{"model":"@anthropic/claude-opus-4-6","stream":true,"tools":[{"name":"read-name","description":"Reads the name of an organization.","inputSchema":{"type":"object","required":["org"],"properties":{"org":{"type":"string","description":"The ID of the referenced object. Formats accepted:\n- DXN (dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4). DXNs can be prepended with an @ symbol for compatibility with in-text references.\n- space ID, object ID tuple (spaceID:objectID)\n- Only object ID that is assumed to be in the current space (01KG7R1ZXWFMWQ4DA1Q6TN1DG4)","examples":["dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","@dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","BM3FSHFOMJCHCG5QW7JTVKGYABD2GAA7G:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","01KG7R1ZXWFMWQ4DA1Q6TN1DG4"]}},"additionalProperties":false}}]},"prompt":{"content":[{"role":"user","content":"What is the name of the organization? 01JGFJJZ00G0WKQSJGMAKCNT89","options":{"anthropic":{"cacheControl":{"ttl":"5m","type":"ephemeral"}}}}]},"response":[{"type":"response-metadata","id":"msg_01FqHQGxFVdQKeMXjodHavsF","modelId":"claude-opus-4-20250514","timestamp":"1970-01-01T00:00:00.000Z","metadata":{}},{"type":"reasoning-start","id":"0","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"The user is asking for the name of","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" an organization an","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"d has provided what","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" appears to be an","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" object","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" ID: 01JGFJ","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"JZ00G0WK","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"QSJGMAKCNT89","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"\n\nI","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" need to use the read-name function","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" to get the name of this organization.","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" According","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" to the function description, I can","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" pass","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" just","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" the object","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" ID if","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" it's assume","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"d to be in the current space.","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"\n\nLet me call","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" the function with this","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" ID.","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"","metadata":{"anthropic":{"type":"thinking","signature":"EokECkYICxgCKkDkOVtqWk3+YJ1nk31yy/hYUygSTbpQxoD7UKl2RqwyS+tJSV2rou35JEFIl30ogJZiohCBXqY0IZ3YO1SwhWq1EgztHHPI5rGjH4gehN8aDBh3BbEfM6OCraoAQiIwDSGtzFCbT7K+yTBtmtri6uuGvPwNGmRshKURPnFRCjdAf0gj1Jwge4pmIYnlGpRGKvACF4kjtsTHsn8f7ktuuzSEpVNaC6d5VYA6/Fm5ZFaiQPn0/F4fQXy1PNEyo4007gP21Ate8+98CCtlfkOnEE53hElq58doXrVOzpL+uH5b6PBPtM9f1+L9cKjhTPV6djIcewwHTTSJDTM6fr9c82f9u5EDvzNe1QODqlqCiVtNsjWCYOWNZUqILdl0TQ43Hzjf2T+WN6ARHfd3mGVsAtg8vcBM8D4mPvThsTnoswYIeB6Y5aDAA+Xu32jGRmJGclevuy25lJFZG8lAhOXJOdiP88zTG5XCN5ED3GLo2rjKBnQzwGpzg1M0ARKkrNzuLbNZ31uk36ayo+1T381Ld0yIQAX/ZUrLNZ8ovJ1sIHW18hmnyec69+4qWuy//NBWlAfyFOQnQfXM1f2XO5AFBrSILGtHxWM1+KINm1Xh68gHZpjjpyM5g8zl61nDLGxNq3OBugM7NSghygmGPmy2DlxU147cVzOHh7ZXh8fFxBfZlW0YAQ=="}}},{"type":"reasoning-end","id":"0","metadata":{}},{"type":"text-start","id":"1","metadata":{}},{"type":"text-delta","id":"1","delta":"I","metadata":{}},{"type":"text-delta","id":"1","delta":"'ll look","metadata":{}},{"type":"text-delta","id":"1","delta":" up the name of that","metadata":{}},{"type":"text-delta","id":"1","delta":" organization for you.","metadata":{}},{"type":"text-end","id":"1","metadata":{}},{"type":"tool-params-start","id":"toolu_01DdHbHNejZJC4CEjngmNLCf","name":"read-name","providerExecuted":false,"metadata":{}},{"type":"tool-params-delta","id":"toolu_01DdHbHNejZJC4CEjngmNLCf","delta":"","metadata":{}},{"type":"tool-params-delta","id":"toolu_01DdHbHNejZJC4CEjngmNLCf","delta":"{\"or","metadata":{}},{"type":"tool-params-delta","id":"toolu_01DdHbHNejZJC4CEjngmNLCf","delta":"g\": \"01JGFJJ","metadata":{}},{"type":"tool-params-delta","id":"toolu_01DdHbHNejZJC4CEjngmNLCf","delta":"Z00G0WKQ","metadata":{}},{"type":"tool-params-delta","id":"toolu_01DdHbHNejZJC4CEjngmNLCf","delta":"SJGM","metadata":{}},{"type":"tool-params-delta","id":"toolu_01DdHbHNejZJC4CEjngmNLCf","delta":"AKCNT89\"}","metadata":{}},{"type":"tool-params-end","id":"toolu_01DdHbHNejZJC4CEjngmNLCf","metadata":{}},{"type":"tool-call","id":"toolu_01DdHbHNejZJC4CEjngmNLCf","name":"read-name","providerExecuted":false,"metadata":{},"params":{"org":"dxn:echo:@:01JGFJJZ00G0WKQSJGMAKCNT89"}},{"type":"finish","reason":"tool-calls","usage":{"inputTokens":729,"outputTokens":187,"totalTokens":916},"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":729,"output_tokens":8,"server_tool_use":null,"service_tier":"standard"}}}}]},{"parameters":{"model":"@anthropic/claude-opus-4-6","stream":true,"tools":[{"name":"read-name","description":"Reads the name of an organization.","inputSchema":{"type":"object","required":["org"],"properties":{"org":{"type":"string","description":"The ID of the referenced object. Formats accepted:\n- DXN (dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4). DXNs can be prepended with an @ symbol for compatibility with in-text references.\n- space ID, object ID tuple (spaceID:objectID)\n- Only object ID that is assumed to be in the current space (01KG7R1ZXWFMWQ4DA1Q6TN1DG4)","examples":["dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","@dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","BM3FSHFOMJCHCG5QW7JTVKGYABD2GAA7G:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","01KG7R1ZXWFMWQ4DA1Q6TN1DG4"]}},"additionalProperties":false}}]},"prompt":{"content":[{"role":"user","content":"What is the name of the organization? 01JGFJJZ00G0WKQSJGMAKCNT89","options":{}},{"role":"assistant","content":[{"type":"reasoning","text":"The user is asking for the name of an organization and has provided what appears to be an object ID: 01JGFJJZ00G0WKQSJGMAKCNT89\n\nI need to use the read-name function to get the name of this organization. According to the function description, I can pass just the object ID if it's assumed to be in the current space.\n\nLet me call the function with this ID.","options":{}},{"type":"text","text":"I'll look up the name of that organization for you.","options":{}},{"type":"tool-call","id":"toolu_01DdHbHNejZJC4CEjngmNLCf","name":"read-name","params":{"org":"01JGFJJZ00G0WKQSJGMAKCNT89"},"providerExecuted":false,"options":{}}],"options":{}},{"role":"tool","content":[{"type":"tool-result","id":"toolu_01DdHbHNejZJC4CEjngmNLCf","name":"read-name","isFailure":false,"result":"BlueYard","providerExecuted":false,"options":{}}],"options":{"anthropic":{"cacheControl":{"ttl":"5m","type":"ephemeral"}}}}]},"response":[{"type":"response-metadata","id":"msg_01X5xvtDymPG7tTUMLZz3eAD","modelId":"claude-opus-4-20250514","timestamp":"1970-01-01T00:00:00.000Z","metadata":{}},{"type":"text-start","id":"0","metadata":{}},{"type":"text-delta","id":"0","delta":"The name of the organization with","metadata":{}},{"type":"text-delta","id":"0","delta":" ID 01JGFJJ","metadata":{}},{"type":"text-delta","id":"0","delta":"Z00G0WKQ","metadata":{}},{"type":"text-delta","id":"0","delta":"SJGMAKCNT89 is","metadata":{}},{"type":"text-delta","id":"0","delta":" **BlueYard**.","metadata":{}},{"type":"text-end","id":"0","metadata":{}},{"type":"finish","reason":"stop","usage":{"inputTokens":801,"outputTokens":39,"totalTokens":840},"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":801,"output_tokens":6,"server_tool_use":null,"service_tier":"standard"}}}}]}]}

package/src/functions.test.ts

@@ -0,0 +1,82 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { ConsolePrinter } from '@dxos/ai';
+import { MemoizedAiService } from '@dxos/ai/testing';
+import { AiSession, GenerationObserver, createToolkit } from '@dxos/assistant';
+import { Blueprint } from '@dxos/blueprints';
+import { Database, Obj, Ref } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { ObjectId } from '@dxos/keys';
+import { Operation, OperationHandlerSet } from '@dxos/operation';
+import { Organization } from '@dxos/types';
+
+import { AssistantTestLayer } from './testing';
+
+ObjectId.dangerouslyDisableRandomness();
+
+const ReadName = Operation.make({
+  meta: {
+    key: 'org.dxos.function.read-name',
+    name: 'Read Name',
+    description: 'Reads the name of an organization.',
+  },
+  input: Schema.Struct({
+    org: Ref.Ref(Organization.Organization),
+  }),
+  output: Schema.String,
+  services: [Database.Service],
+});
+
+const Handlers = OperationHandlerSet.make(
+  Operation.withHandler(
+    ReadName,
+    Effect.fnUntraced(function* ({ org }) {
+      const resolved = yield* Database.load(org);
+      return resolved.name ?? '<no org>';
+    }),
+  ),
+);
+
+const blueprint = Blueprint.make({
+  key: 'org.dxos.blueprint.test',
+  name: 'Test blueprint',
+  tools: Blueprint.toolDefinitions({ operations: [ReadName] }),
+});
+
+const TestLayer = AssistantTestLayer({
+  aiServicePreset: 'edge-remote',
+  operationHandlers: Handlers,
+  types: [Organization.Organization],
+});
+
+describe('Research', () => {
+  it.effect(
+    'call a function with a ref input',
+    Effect.fnUntraced(
+      function* (_) {
+        const org = yield* Database.add(
+          Obj.make(Organization.Organization, {
+            name: 'BlueYard',
+            website: 'https://blueyard.com',
+          }),
+        );
+        yield* Database.flush();
+        yield* new AiSession({ observer: GenerationObserver.fromPrinter(new ConsolePrinter()) }).run({
+          prompt: `What is the name of the organization? ${org.id}`,
+          toolkit: yield* createToolkit({
+            blueprints: [blueprint],
+          }),
+        });
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+    MemoizedAiService.isGenerationEnabled() ? 240_000 : 30_000,
+  );
+});

package/src/index.ts

@@ -2,11 +2,13 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './context';
 export * from './conversation';
-export * from './extraction';
+export * from './diff';
+export * from './errors';
+export * from './execution-graph';
 export * from './functions';
-export * from './research';
 export * from './session';
 export * from './templates';
 export * from './types';
+export * from './service';
+export * from './tracing';