@dxos/assistant 0.8.4-main.ead640a → 0.8.4-main.ef1bc66f44

package/src/extraction/extraction-ner-function/extraction-ner-function.ts

@@ -2,18 +2,9 @@
 // Copyright 2025 DXOS.org
 //
 
-// ISSUE(burdon): defineFunction
-// @ts-nocheck
-
-import { asyncTimeout } from '@dxos/async';
-import { create } from '@dxos/echo/internal';
-import { DatabaseService, defineFunction } from '@dxos/functions';
-import { invariant } from '@dxos/invariant';
-import { log } from '@dxos/log';
-import { DataType } from '@dxos/schema';
+import { defineFunction } from '@dxos/functions';
 
 import { ExtractionInput, ExtractionOutput } from '../extraction';
-import { findQuotes, insertReferences } from '../quotes';
 
 /**
  * Named Entity Recognition model
@@ -26,39 +17,40 @@ export const extractionNerFunction = defineFunction({
   inputSchema: ExtractionInput,
   outputSchema: ExtractionOutput,
   handler: async ({ data: { message, options }, context }) => {
-    log.info('input', { message, options });
-    const startTime = performance.now();
-    const { db } = context.getService(DatabaseService);
-    const { extractFullEntities } = await import('./named-entity-recognition');
-
-    const entitiesPromise = Promise.all(
-      message.blocks.map(async (block) => {
-        invariant(block._tag === 'transcript' || block._tag === 'text');
-        return extractFullEntities(block.text);
-      }),
-    ).then((entities) => entities.flat());
-    const entities = options?.timeout ? await asyncTimeout(entitiesPromise, options.timeout) : await entitiesPromise;
-
-    log.info('entities', { entities });
-    const quoteReferences = await findQuotes(
-      entities.map((entity) => entity.word),
-      db,
-    );
-
-    const blocksWithReferences = message.blocks.map((block) => {
-      invariant(block._tag === 'transcript' || block._tag === 'text');
-      return { ...block, text: insertReferences(block._tag, quoteReferences) };
-    });
-
-    const messageWithReferences = create(DataType.Message, {
-      ...message,
-      blocks: blocksWithReferences,
-    });
-
-    log.info('output', { messageWithReferences });
-    return {
-      message: messageWithReferences,
-      timeElapsed: performance.now() - startTime,
-    };
+    throw new Error('not implemented');
+    // log.info('input', { message, options });
+    // const startTime = performance.now();
+    // const { db } = context.getService(Database.Service);
+    // const { extractFullEntities } = await import('./named-entity-recognition');
+
+    // const entitiesPromise = Promise.all(
+    //   message.blocks.map(async (block) => {
+    //     invariant(block._tag === 'transcript' || block._tag === 'text');
+    //     return extractFullEntities(block.text);
+    //   }),
+    // ).then((entities) => entities.flat());
+    // const entities = options?.timeout ? await asyncTimeout(entitiesPromise, options.timeout) : await entitiesPromise;
+
+    // log.info('entities', { entities });
+    // const quoteReferences = await findQuotes(
+    //   entities.map((entity) => entity.word),
+    //   db,
+    // );
+
+    // const blocksWithReferences = message.blocks.map((block) => {
+    //   invariant(block._tag === 'transcript' || block._tag === 'text');
+    //   return { ...block, text: insertReferences(block._tag, quoteReferences) };
+    // });
+
+    // const messageWithReferences = create(Message.Message, {
+    //   ...message,
+    //   blocks: blocksWithReferences,
+    // });
+
+    // log.info('output', { messageWithReferences });
+    // return {
+    //   message: messageWithReferences,
+    //   timeElapsed: performance.now() - startTime,
+    // };
   },
 });

package/src/extraction/extraction-ner-function/named-entity-recognition.test.ts

@@ -6,7 +6,8 @@ import { type TokenClassificationOutput, type TokenClassificationPipelineType }
 import { beforeAll, describe, expect, test } from 'vitest';
 
 import { log } from '@dxos/log';
-import { createTestData } from '@dxos/schema/testing';
+import { type ContentBlock, type Message } from '@dxos/types';
+import { createTestData } from '@dxos/types/testing';
 
 import { combineNerTokens, createTokenGroups, extractFullEntities, getNer } from './named-entity-recognition';
 
@@ -57,8 +58,10 @@ describe.skip('NamedEntityRecognition', () => {
   test('own data', async () => {
     const { transcriptWoflram, transcriptJosiah } = await createTestData();
 
-    const blocks = [...transcriptWoflram, ...transcriptJosiah].flatMap((message) =>
-      message.blocks.flatMap((block) => (block._tag === 'transcript' ? [block.text] : [])),
+    const blocks = [...transcriptWoflram, ...transcriptJosiah].flatMap((message: Message.Message) =>
+      message.blocks.flatMap((block: ContentBlock.Any) =>
+        block._tag === 'transcript' ? [(block as ContentBlock.Transcript).text] : [],
+      ),
     );
 
     for (const block of blocks) {
@@ -70,8 +73,10 @@ describe.skip('NamedEntityRecognition', () => {
   test('more own data', async () => {
     const { transcriptMessages } = await createTestData();
 
-    const blocks = transcriptMessages.flatMap((message) =>
-      message.blocks.flatMap((block) => (block._tag === 'transcript' ? [block.text] : [])),
+    const blocks = transcriptMessages.flatMap((message: Message.Message) =>
+      message.blocks.flatMap((block: ContentBlock.Any) =>
+        block._tag === 'transcript' ? [(block as ContentBlock.Transcript).text] : [],
+      ),
     );
 
     for (const block of blocks) {

package/src/extraction/extraction.ts

@@ -5,14 +5,15 @@
 import * as Schema from 'effect/Schema';
 
 import { asyncTimeout } from '@dxos/async';
-import { Expando } from '@dxos/echo/internal';
-import { type FunctionDefinition, type FunctionExecutor } from '@dxos/functions';
+import { Type } from '@dxos/echo';
+import { type FunctionDefinition } from '@dxos/functions';
+import { type FunctionExecutor } from '@dxos/functions-runtime';
 import { log } from '@dxos/log';
-import { DataType } from '@dxos/schema';
+import { Message } from '@dxos/types';
 
 export const ExtractionInput = Schema.Struct({
-  message: DataType.Message,
-  objects: Schema.optional(Schema.Array(Expando)),
+  message: Message.Message,
+  objects: Schema.optional(Schema.Array(Type.Obj)),
   options: Schema.optional(
     Schema.Struct({
       timeout: Schema.optional(Schema.Number),
@@ -23,12 +24,12 @@ export const ExtractionInput = Schema.Struct({
 export interface ExtractionInput extends Schema.Schema.Type<typeof ExtractionInput> {}
 
 export const ExtractionOutput = Schema.Struct({
-  message: DataType.Message,
+  message: Message.Message,
   timeElapsed: Schema.Number,
 });
 export interface ExtractionOutput extends Schema.Schema.Type<typeof ExtractionOutput> {}
 
-export type ProcessTranscriptMessageParams = {
+export type ProcessTranscriptMessageProps = {
   input: ExtractionInput;
   function: FunctionDefinition<ExtractionInput, ExtractionOutput>;
   executor: FunctionExecutor;
@@ -54,7 +55,7 @@ export type ExtractionFunction = FunctionDefinition<ExtractionInput, ExtractionO
  * Extract entities from the transcript message and add them to the message.
  */
 // TODO(dmaretskyi): Move context to a vector search index.
-export const processTranscriptMessage = async (params: ProcessTranscriptMessageParams): Promise<ExtractionOutput> => {
+export const processTranscriptMessage = async (params: ProcessTranscriptMessageProps): Promise<ExtractionOutput> => {
   try {
     if (params.options?.timeout && params.options.timeout > 0) {
       return await asyncTimeout(params.executor.invoke(params.function, params.input), params.options.timeout);

package/src/extraction/quotes.ts

@@ -4,9 +4,8 @@
 
 import * as Schema from 'effect/Schema';
 
-import { Filter, Query } from '@dxos/echo';
-import { ObjectId } from '@dxos/echo/internal';
-import { type EchoDatabase } from '@dxos/echo-db';
+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 }] : [];
     }),

package/src/functions/services.ts

@@ -9,13 +9,17 @@ 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 type * as SchemaAST from 'effect/SchemaAST';
 
 import { AiToolNotFoundError, ToolExecutionService, ToolResolverService } from '@dxos/ai';
 import { todo } from '@dxos/debug';
-import { Query } from '@dxos/echo';
-import { DatabaseService, FunctionDefinition, FunctionInvocationService, FunctionType } from '@dxos/functions';
+import { Type } from '@dxos/echo';
+import { type FunctionDefinition, FunctionInvocationService } from '@dxos/functions';
 import { invariant } from '@dxos/invariant';
 
+import { GenericToolkit } from '../session';
+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`.
@@ -25,51 +29,50 @@ import { invariant } from '@dxos/invariant';
  *
  * If none of the above yield a match, the effect fails with `AiToolNotFoundError`.
  *
- * Requires `DatabaseService` in the environment.
+ * Requires `Database.Service` in the environment.
  */
-export const makeToolResolverFromFunctions = (
-  functions: FunctionDefinition<any, any>[],
-  toolkit: Toolkit.Toolkit<any>,
-): Layer.Layer<ToolResolverService, never, DatabaseService> => {
+export const makeToolResolverFromFunctions = (): Layer.Layer<
+  ToolResolverService,
+  never,
+  GenericToolkit.Provider | FunctionInvocationService
+> => {
   return Layer.effect(
     ToolResolverService,
     Effect.gen(function* () {
-      const dbService = yield* DatabaseService;
+      const toolkitProvider = yield* GenericToolkit.Provider;
+      const functionInvocationService = yield* FunctionInvocationService;
       return {
         resolve: (id): Effect.Effect<Tool.Any, AiToolNotFoundError> =>
           Effect.gen(function* () {
-            const tool = toolkit.tools[id];
+            const toolkit = toolkitProvider.getToolkit();
+
+            const tool = toolkit.toolkit.tools[id];
             if (tool) {
               return tool;
             }
 
-            const {
-              objects: [dbFunction],
-            } = yield* DatabaseService.runQuery(Query.type(FunctionType, { key: id }));
-
-            const functionDef = dbFunction
-              ? FunctionDefinition.deserialize(dbFunction)
-              : functions.find((fn) => fn.key === id);
-
-            if (!functionDef) {
-              return yield* Effect.fail(new AiToolNotFoundError(id));
-            }
-
-            return projectFunctionToTool(functionDef);
-          }).pipe(Effect.provideService(DatabaseService, dbService)),
+            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 = (
-  toolkit: Toolkit.Toolkit<any>,
-  handlersLayer: Layer.Layer<Tool.Handler<any>, never, never>,
-): Layer.Layer<ToolExecutionService, never, FunctionInvocationService> => {
+export const makeToolExecutionServiceFromFunctions = (): Layer.Layer<
+  ToolExecutionService,
+  never,
+  FunctionInvocationService | GenericToolkit.Provider
+> => {
   return Layer.effect(
     ToolExecutionService,
     Effect.gen(function* () {
-      const toolkitHandler = yield* toolkit.pipe(Effect.provide(handlersLayer));
+      const toolkitProvider = yield* GenericToolkit.Provider;
+      const toolkit = toolkitProvider.getToolkit();
+
+      const toolkitHandler = yield* toolkit.toolkit.pipe(Effect.provide(toolkit.layer));
       invariant(isHandlerLike(toolkitHandler));
       const functionInvocationService = yield* FunctionInvocationService;
 
@@ -81,8 +84,10 @@ export const makeToolExecutionServiceFromFunctions = (
                 if (Tool.isProviderDefined(tool)) {
                   throw new Error('Attempted to call a provider-defined tool');
                 }
+
                 // TODO(wittjosiah): Everything is `never` here.
-                return yield* (toolkitHandler.handle as any)(tool.name, input);
+                const { result } = yield* (toolkitHandler.handle as any)(tool.name, input);
+                return result;
               }
 
               const { definition: functionDef } = Context.get(FunctionToolAnnotation)(tool.annotations as any);
@@ -102,26 +107,33 @@ export const makeToolExecutionServiceFromFunctions = (
   );
 };
 
+export const ToolExecutionServices = Layer.mergeAll(
+  makeToolResolverFromFunctions(),
+  makeToolExecutionServiceFromFunctions(),
+);
+
 class FunctionToolAnnotation extends Context.Tag('@dxos/assistant/FunctionToolAnnotation')<
   FunctionToolAnnotation,
-  { definition: FunctionDefinition<any, any> }
+  { definition: FunctionDefinition.Any }
 >() {}
 
-const toolCache = new WeakMap<FunctionDefinition<any, any>, Tool.Any>();
+const toolCache = new WeakMap<FunctionDefinition.Any, Tool.Any>();
 
 /**
  * Projects a `FunctionDefinition` into an `AiTool`.
  *
  * @param fn The function definition to project into a tool.
  * @param meta Optional projection metadata.
- * @param meta.deployedFunctionId Backend deployment ID used for remote invocation when present. This is the
- *        EDGE service's function deployment identifier (not the ECHO object ID/DXN and not `FunctionDefinition.key`).
+ * @param meta.deployedFunctionId Backend deployment ID used for remote invocation when present.
+ *    This is the EDGE service's function deployment identifier (not the ECHO object ID/DXN and not `FunctionDefinition.key`).
  */
-const projectFunctionToTool = (fn: FunctionDefinition<any, any>): Tool.Any => {
+const projectFunctionToTool = (fn: FunctionDefinition.Any): Tool.Any => {
   if (toolCache.has(fn)) {
     return toolCache.get(fn)!;
   }
 
+  // TODO(burdon): Use and map function.key?
+  // TODO(dmaretskyi): Use function key instead.
   const tool = Tool.make(makeToolName(fn.name), {
     description: fn.description,
     parameters: createStructFieldsFromSchema(fn.inputSchema),
@@ -136,8 +148,8 @@ const projectFunctionToTool = (fn: FunctionDefinition<any, any>): Tool.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;
 };
 
@@ -145,7 +157,9 @@ 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:
@@ -153,6 +167,21 @@ const createStructFieldsFromSchema = (schema: Schema.Schema<any, any>): Record<s
   }
 };
 
+/**
+ * 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 (Type.Ref.isRefSchemaAST(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;
+  }
+
+  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/functions.conversations.json

@@ -0,0 +1 @@
+{"conversations":[{"parameters":{"model":"@anthropic/claude-opus-4-0","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-0","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,74 @@
+//
+// 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, Type } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { defineFunction } from '@dxos/functions';
+import { ObjectId } from '@dxos/keys';
+import { Organization } from '@dxos/types';
+
+import { AssistantTestLayer } from './testing';
+
+ObjectId.dangerouslyDisableRandomness();
+
+const readName = defineFunction({
+  key: 'dxos.org/function/read-name',
+  name: 'Read Name',
+  description: 'Reads the name of an organization.',
+  inputSchema: Schema.Struct({
+    org: Type.Ref(Organization.Organization),
+  }),
+  outputSchema: Schema.String,
+  handler: Effect.fnUntraced(function* ({ data }) {
+    const org = yield* Database.load(data.org);
+    return org.name ?? '<no org>';
+  }),
+});
+
+const blueprint = Blueprint.make({
+  key: 'dxos.org/blueprint/test',
+  name: 'Test blueprint',
+  tools: Blueprint.toolDefinitions({ functions: [readName] }),
+});
+
+const TestLayer = AssistantTestLayer({
+  aiServicePreset: 'edge-remote',
+  functions: [readName],
+  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({ indexes: true });
+        yield* new AiSession().run({
+          prompt: `What is the name of the organization? ${org.id}`,
+          toolkit: yield* createToolkit({
+            blueprints: [blueprint],
+          }),
+          observer: GenerationObserver.fromPrinter(new ConsolePrinter()),
+        });
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+    MemoizedAiService.isGenerationEnabled() ? 240_000 : 30_000,
+  );
+});

package/src/session/GenericToolkit.ts

@@ -0,0 +1,160 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Tool from '@effect/ai/Tool';
+import * 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 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);
+    },
+  };
+};
+
+/**
+ * Empty generic toolkit.
+ */
+export const empty = make(Toolkit.empty, Layer.empty);
+
+/**
+ * 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;
+      readonly failureMode: Tool.FailureMode;
+    },
+    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;
+}
+
+/**
+ * Provides a generic toolkit to the agent.
+ */
+export class Provider extends Context.Tag('@dxos/assistant/GenericToolkit.Provider')<
+  Provider,
+  {
+    readonly getToolkit: () => GenericToolkit;
+  }
+>() {}
+
+/**
+ * Layer for providing a generic toolkit to the agent.
+ */
+export const providerLayer = (toolkit: GenericToolkit) =>
+  Layer.succeed(Provider, {
+    getToolkit: () => toolkit,
+  });
+
+/**
+ * Layer for providing an empty generic toolkit to the agent.
+ */
+export const providerEmpty = providerLayer(empty);