@dxos/assistant 0.8.4-main.7ace549 → 0.8.4-main.937b3ca

package/src/session/observer.ts

@@ -2,6 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
+import type * as Tool from '@effect/ai/Tool';
 import * as Effect from 'effect/Effect';
 import * as Function from 'effect/Function';
 
@@ -11,7 +12,8 @@ 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.

package/src/session/session.conversations.json

@@ -1 +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"}}}}]}]}
+{"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","isFailure":false,"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"}}}}]},{"parameters":{"model":"@anthropic/claude-opus-4-0","stream":true,"tools":[]},"prompt":{"content":[{"role":"user","content":"Hello world!","options":{}}]},"response":[{"type":"response-metadata","id":"msg_01QPPeofAkjiYa83LPCeSYfS","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":"Hello!","metadata":{}},{"type":"text-delta","id":"0","delta":" Welcome","metadata":{}},{"type":"text-delta","id":"0","delta":" to the worl","metadata":{}},{"type":"text-delta","id":"0","delta":"d!","metadata":{}},{"type":"text-delta","id":"0","delta":" 🌍 ","metadata":{}},{"type":"text-delta","id":"0","delta":"How","metadata":{}},{"type":"text-delta","id":"0","delta":" are you doing today? Is there anything","metadata":{}},{"type":"text-delta","id":"0","delta":" specific you'd like to chat about or","metadata":{}},{"type":"text-delta","id":"0","delta":" any questions","metadata":{}},{"type":"text-delta","id":"0","delta":" I can help you with?","metadata":{}},{"type":"text-end","id":"0","metadata":{}},{"type":"finish","reason":"stop","usage":{"inputTokens":10,"outputTokens":40,"totalTokens":50},"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":2,"server_tool_use":null,"service_tier":"standard"}}}}]},{"parameters":{"model":"@anthropic/claude-opus-4-0","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_01EaHNEDYN3Hvp5toY8hQGe6","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":"I'll help","metadata":{}},{"type":"text-delta","id":"0","delta":" you calculate ","metadata":{}},{"type":"text-delta","id":"0","delta":"10 + 30.","metadata":{}},{"type":"text-end","id":"0","metadata":{}},{"type":"tool-params-start","id":"toolu_01X4qkrMwCisiUN8Cm4E4Voe","name":"Calculator","providerExecuted":false,"metadata":{}},{"type":"tool-params-delta","id":"toolu_01X4qkrMwCisiUN8Cm4E4Voe","delta":"","metadata":{}},{"type":"tool-params-delta","id":"toolu_01X4qkrMwCisiUN8Cm4E4Voe","delta":"{\"input\": ","metadata":{}},{"type":"tool-params-delta","id":"toolu_01X4qkrMwCisiUN8Cm4E4Voe","delta":"\"10 + 3","metadata":{}},{"type":"tool-params-delta","id":"toolu_01X4qkrMwCisiUN8Cm4E4Voe","delta":"0\"}","metadata":{}},{"type":"tool-params-end","id":"toolu_01X4qkrMwCisiUN8Cm4E4Voe","metadata":{}},{"type":"tool-call","id":"toolu_01X4qkrMwCisiUN8Cm4E4Voe","name":"Calculator","params":{"input":"10 + 30"},"providerExecuted":false,"metadata":{}},{"type":"finish","reason":"tool-calls","usage":{"inputTokens":394,"outputTokens":68,"totalTokens":462},"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":3,"server_tool_use":null,"service_tier":"standard"}}}}]},{"parameters":{"model":"@anthropic/claude-opus-4-0","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.","options":{}},{"type":"tool-call","id":"toolu_01X4qkrMwCisiUN8Cm4E4Voe","name":"Calculator","params":{"input":"10 + 30"},"providerExecuted":false,"options":{}}],"options":{}},{"role":"tool","content":[{"type":"tool-result","id":"toolu_01X4qkrMwCisiUN8Cm4E4Voe","name":"Calculator","isFailure":false,"result":{"result":40},"options":{}}],"options":{}}]},"response":[{"type":"response-metadata","id":"msg_01RjnEkFT3iEUFCpfC4B28aS","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":"10 + 30 = ","metadata":{}},{"type":"text-delta","id":"0","delta":"40","metadata":{}},{"type":"text-end","id":"0","metadata":{}},{"type":"finish","reason":"stop","usage":{"inputTokens":478,"outputTokens":12,"totalTokens":490},"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":478,"output_tokens":8,"server_tool_use":null,"service_tier":"standard"}}}}]}]}

package/src/session/session.test.ts

@@ -9,13 +9,12 @@ import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
 import * as Schema from 'effect/Schema';
 
-import { AiService, MemoizedAiService, ToolExecutionService, ToolResolverService } from '@dxos/ai';
-import { AiServiceTestingPreset } from '@dxos/ai/testing';
 import { Obj, Type } from '@dxos/echo';
-import { TestHelpers } from '@dxos/effect';
-import { TracingService } from '@dxos/functions';
+import { TestHelpers } from '@dxos/effect/testing';
 import { log } from '@dxos/log';
 
+import { AssistantTestLayer } from '../testing';
+
 import { AiSession } from './session';
 
 // Define a calendar event artifact schema.
@@ -25,7 +24,7 @@ const CalendarEventSchema = Schema.Struct({
   endTime: Schema.String,
   description: Schema.String,
 }).pipe(
-  Type.Obj({
+  Type.object({
     typename: 'example.com/type/CalendarEvent',
     version: '0.1.0',
   }),
@@ -66,15 +65,10 @@ const toolkitLayer = TestToolkit.toLayer({
 });
 
 const TestLayer = Layer.mergeAll(
+  AssistantTestLayer({
+    types: [CalendarEventSchema],
+  }),
   toolkitLayer,
-  AiService.model('@anthropic/claude-3-5-sonnet-20241022'),
-  TracingService.layerNoop,
-  ToolResolverService.layerEmpty,
-  ToolExecutionService.layerEmpty,
-).pipe(
-  //
-  Layer.provideMerge(MemoizedAiService.layerTest()),
-  Layer.provide(AiServiceTestingPreset('direct')),
 );
 
 describe('AiSession', () => {

package/src/session/session.ts

@@ -24,7 +24,7 @@ import {
 import { type Blueprint } from '@dxos/blueprints';
 import { todo } from '@dxos/debug';
 import { Obj } from '@dxos/echo';
-import { TracingService } from '@dxos/functions';
+import { type FunctionInvocationService, TracingService } from '@dxos/functions';
 import { log } from '@dxos/log';
 import { Message } from '@dxos/types';
 
@@ -39,21 +39,22 @@ export type AiSessionRunRequirements =
   | LanguageModel.LanguageModel
   | ToolExecutionService
   | ToolResolverService
-  | TracingService;
+  | TracingService
+  | FunctionInvocationService;
 
-export type AiSessionRunParams<Tools extends Record<string, Tool.Any>> = {
+export type AiSessionOptions = {};
+
+export type AiSessionRunProps<Tools extends Record<string, Tool.Any>> = {
   prompt: string;
   // TODO(wittjosiah): Rename to systemPrompt.
   system?: string;
   history?: Message.Message[];
-  objects?: Obj.Any[];
-  blueprints?: Blueprint.Blueprint[];
+  objects?: Obj.Unknown[];
+  blueprints?: readonly Blueprint.Blueprint[];
   toolkit?: Toolkit.WithHandler<Tools>;
-  observer?: GenerationObserver;
+  observer?: GenerationObserver<Tools>;
 };
 
-export type AiSessionOptions = {};
-
 /**
  * Contains message history, tools, current context.
  * Current context means the state of the app, time of day, and other contextual information.
@@ -75,8 +76,20 @@ export class AiSession {
   /** Pending messages for this session (incl. the current prompt). */
   private _pending: Message.Message[] = [];
 
+  private _started = 0;
+  private _ended = 0;
+  private _toolCalls = 0;
+
   constructor(private readonly _options: AiSessionOptions = {}) {}
 
+  get duration(): number {
+    return this._ended - this._started;
+  }
+
+  get toolCalls(): number {
+    return this._toolCalls;
+  }
+
   run = <Tools extends Record<string, Tool.Any>>({
     prompt,
     system: systemTemplate,
@@ -85,8 +98,9 @@ export class AiSession {
     blueprints = [],
     toolkit,
     observer = GenerationObserver.noop(),
-  }: AiSessionRunParams<Tools>): Effect.Effect<Message.Message[], AiSessionRunError, AiSessionRunRequirements> =>
+  }: AiSessionRunProps<Tools>): Effect.Effect<Message.Message[], AiSessionRunError, AiSessionRunRequirements> =>
     Effect.gen(this, function* () {
+      this._started = Date.now();
       this._history = [...history];
       this._pending = [];
       const pending = this._pending;
@@ -103,7 +117,9 @@ export class AiSession {
       const promptMessage = yield* submitMessage(yield* formatUserPrompt({ prompt, history }));
 
       // Generate system and prompt messages.
-      const system = yield* formatSystemPrompt({ system: systemTemplate, blueprints, objects });
+      const system = yield* formatSystemPrompt({ system: systemTemplate, blueprints, objects }).pipe(Effect.orDie);
+
+      // log('system', { prompt: system });
 
       // Tool call loop.
       do {
@@ -135,6 +151,8 @@ export class AiSession {
           Effect.map(Chunk.toArray),
         );
 
+        // log('blocks', { blocks });
+
         // Create the response message.
         const response = yield* submitMessage(
           Obj.make(Message.Message, {
@@ -176,9 +194,12 @@ export class AiSession {
             blocks: toolResults,
           }),
         );
+
+        this._toolCalls++;
       } while (true);
 
-      log('done', { pending: this._pending.length });
+      this._ended = Date.now();
+      log('done', { pending: this._pending.length, duration: this.duration, tools: this._toolCalls });
       return this._pending;
     }).pipe(this._semaphore.withPermits(1), Effect.withSpan('AiSession.run'));
 
@@ -188,7 +209,7 @@ export class AiSession {
   // TODO(burdon): Implement or remove.
   async runStructured<S extends Schema.Schema.AnyNoContext>(
     _schema: S,
-    _options: AiSessionRunParams<any>,
+    _options: AiSessionRunProps<any>,
   ): Promise<Schema.Schema.Type<S>> {
     return todo();
     // const parser = structuredOutputParser(schema);

package/src/session/toolkit.ts

@@ -4,45 +4,36 @@
 
 import type * as Tool from '@effect/ai/Tool';
 import * as Toolkit from '@effect/ai/Toolkit';
-import type * as Context from 'effect/Context';
 import * as Effect from 'effect/Effect';
 
-import { type AiToolNotFoundError, ToolExecutionService, type ToolId, ToolResolverService } from '@dxos/ai';
+import { type AiToolNotFoundError, ToolExecutionService, ToolResolverService } from '@dxos/ai';
 import { type Blueprint } from '@dxos/blueprints';
 import { isTruthy } from '@dxos/util';
 
-export type ToolkitParams<Tools extends Record<string, Tool.Any>> = {
-  toolkit?: Toolkit.Toolkit<Tools>;
-  toolIds?: ToolId[];
-  blueprints?: Blueprint.Blueprint[];
+export type CreateToolkitProps = {
+  toolkit?: Toolkit.Any;
+  blueprints?: readonly Blueprint.Blueprint[];
 };
 
 /**
  * Build a combined toolkit from the blueprint tools and the provided toolkit.
  */
-export const createToolkit = <Tools extends Record<string, Tool.Any> = {}>({
-  toolkit: toolkitParam,
-  toolIds = [],
+export const createToolkit = ({
+  toolkit: toolkitProp,
   blueprints = [],
-}: ToolkitParams<Tools>): Effect.Effect<
+}: CreateToolkitProps): Effect.Effect<
   Toolkit.WithHandler<any>,
   AiToolNotFoundError,
-  ToolResolverService | ToolExecutionService | Tool.HandlersFor<Tools>
+  ToolResolverService | ToolExecutionService | Tool.HandlersFor<any>
 > =>
   Effect.gen(function* () {
-    const blueprintToolkit = yield* ToolResolverService.resolveToolkit([
-      ...blueprints.flatMap(({ tools }) => tools),
-      ...toolIds,
-    ]);
+    const blueprintToolkit = yield* ToolResolverService.resolveToolkit(blueprints.flatMap(({ tools }) => tools));
+    const blueprintToolHandler = yield* blueprintToolkit.toContext(ToolExecutionService.handlersFor(blueprintToolkit));
 
-    const blueprintToolkitHandler: Context.Context<Tool.HandlersFor<any>> = yield* blueprintToolkit.toContext(
-      ToolExecutionService.handlersFor(blueprintToolkit),
-    );
-
-    const toolkit = Toolkit.merge(...[toolkitParam, blueprintToolkit].filter(isTruthy));
-    return yield* toolkit.pipe(Effect.provide(blueprintToolkitHandler)) as any as Effect.Effect<
+    const toolkit = Toolkit.merge(...[toolkitProp, blueprintToolkit].filter(isTruthy));
+    return yield* toolkit.pipe(Effect.provide(blueprintToolHandler)) as any as Effect.Effect<
       Toolkit.WithHandler<any>,
       never,
-      Tool.HandlersFor<Tools>
+      Tool.HandlersFor<any>
     >;
   });

package/src/session/version-pin.ts

@@ -27,11 +27,11 @@ export interface VersionPin extends Schema.Schema.Type<typeof VersionPinSchema>
 
 export const VersionPin: typeof VersionPinSchema & {
   DISPOSITION: 'version-pin';
-  fromObject: (object: Obj.Any) => VersionPin;
+  fromObject: (object: Obj.Unknown) => VersionPin;
   createBlock: (pin: VersionPin) => ContentBlock.Any;
 } = class extends VersionPinSchema {
   static readonly DISPOSITION = 'version-pin';
-  static fromObject(object: Obj.Any): VersionPin {
+  static fromObject(object: Obj.Unknown): VersionPin {
     return VersionPin.make({
       objectId: object.id,
       version: getVersion(object),

package/src/testing/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './layer';

package/src/testing/layer.ts

@@ -0,0 +1,78 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Layer from 'effect/Layer';
+import * as Match from 'effect/Match';
+
+import { AiService, type ModelName } from '@dxos/ai';
+import { TestAiService } from '@dxos/ai/testing';
+import type { Type } from '@dxos/echo';
+import { CredentialsService, type FunctionDefinition, type ServiceCredential, TracingService } from '@dxos/functions';
+import { TracingServiceExt, TriggerDispatcher, TriggerStateStore } from '@dxos/functions-runtime';
+import { FunctionInvocationServiceLayerTest, TestDatabaseLayer } from '@dxos/functions-runtime/testing';
+
+import { makeToolExecutionServiceFromFunctions, makeToolResolverFromFunctions } from '../functions';
+import { GenericToolkit } from '../session';
+
+interface TestLayerOptions {
+  aiServicePreset?: 'direct' | 'edge-local' | 'edge-remote';
+  model?: ModelName;
+  functions?: FunctionDefinition.Any[];
+  toolkits?: GenericToolkit.GenericToolkit[];
+  types?: Type.Entity.Any[];
+  credentials?: ServiceCredential[];
+  /*
+   * Tracing configuration.
+   * @default 'noop'
+   */
+  tracing?: 'noop' | 'console' | 'pretty';
+}
+
+export const AssistantTestLayer = ({
+  aiServicePreset = 'direct',
+  model = '@anthropic/claude-opus-4-0',
+  functions = [],
+  toolkits = [],
+  types = [],
+  credentials = [],
+  tracing = 'noop',
+}: TestLayerOptions) =>
+  Layer.mergeAll(
+    AiService.model(model),
+    makeToolResolverFromFunctions(functions, GenericToolkit.merge(...toolkits).toolkit as any),
+    makeToolExecutionServiceFromFunctions(
+      GenericToolkit.merge(...toolkits).toolkit as any,
+      GenericToolkit.merge(...toolkits).layer as any,
+    ),
+  ).pipe(
+    Layer.provideMerge(
+      FunctionInvocationServiceLayerTest({
+        functions,
+      }),
+    ),
+    Layer.provideMerge(
+      Layer.mergeAll(
+        TestAiService({ preset: aiServicePreset }),
+        TestDatabaseLayer({
+          spaceKey: 'fixed',
+          types,
+        }),
+        CredentialsService.configuredLayer(credentials),
+        Match.value(tracing).pipe(
+          Match.when('noop', () => TracingService.layerNoop),
+          Match.when('console', () => TracingServiceExt.layerLogInfo()),
+          Match.when('pretty', () => TracingServiceExt.layerConsolePrettyPrint()),
+          Match.exhaustive,
+        ),
+      ),
+    ),
+  );
+
+interface TestLayerWithTriggersOptions extends TestLayerOptions {}
+
+export const AssistantTestLayerWithTriggers = (options: TestLayerWithTriggersOptions) =>
+  Layer.mergeAll(
+    AssistantTestLayer(options),
+    TriggerDispatcher.layer({ timeControl: 'manual', startingTime: new Date('2025-09-05T15:01:00.000Z') }),
+  ).pipe(Layer.provideMerge(TriggerStateStore.layerMemory));

package/src/types/artifact.ts

@@ -5,8 +5,9 @@
 import type * as Effect from 'effect/Effect';
 import * as Schema from 'effect/Schema';
 
-import { type ObjectNotFoundError, type Type } from '@dxos/echo';
-import { DatabaseService } from '@dxos/echo-db';
+import { type Err, Type } from '@dxos/echo';
+import { Database } from '@dxos/echo';
+import { EncodedReference } from '@dxos/echo-protocol';
 import { DXN, LOCAL_SPACE_TAG, type ObjectId, type SpaceId } from '@dxos/keys';
 import { trim } from '@dxos/util';
 
@@ -18,14 +19,16 @@ export const createArtifactElement = (id: ObjectId) => `<artifact id=${id} />`;
 /**
  * A model-friendly way to reference an object.
  * Supports vairous formats that will be normalized to a DXN.
+ *
+ * @deprecated Use `RefFromLLM` instead.
  */
-// TODO(burdon): Rename RefFromLLM?
+// TODO(burdon): Rename RefFromLLM? -- yes -dm
 export const ArtifactId: Schema.Schema<string> & {
   toDXN: (reference: ArtifactId, owningSpaceId?: SpaceId) => DXN;
   resolve: <S extends Type.Entity.Any>(
     schema: S,
     ref: ArtifactId,
-  ) => Effect.Effect<Schema.Schema.Type<S>, ObjectNotFoundError, DatabaseService>;
+  ) => Effect.Effect<Schema.Schema.Type<S>, Err.ObjectNotFoundError, Database.Service>;
 } = class extends Schema.String.annotations({
   // TODO(dmaretskyi): This section gets overriden.
   description: trim`
@@ -61,10 +64,19 @@ export const ArtifactId: Schema.Schema<string> & {
   static resolve<S extends Type.Entity.Any>(
     schema: S,
     ref: ArtifactId,
-  ): Effect.Effect<Schema.Schema.Type<S>, ObjectNotFoundError, DatabaseService> {
+  ): Effect.Effect<Schema.Schema.Type<S>, Err.ObjectNotFoundError, Database.Service> {
     const dxn = ArtifactId.toDXN(ref);
-    return DatabaseService.resolve(dxn, schema);
+    return Database.Service.resolve(dxn, schema);
   }
 };
 
 export type ArtifactId = Schema.Schema.Type<typeof ArtifactId>;
+
+/**
+ * Schema that decodes ECHO reference object from an LLM-friendly input.
+ */
+export const RefFromLLM = Schema.transform(ArtifactId, Type.Ref(Type.Obj), {
+  decode: (fromA, fromI) => EncodedReference.fromDXN(ArtifactId.toDXN(fromA)),
+  encode: (toI, toA) => EncodedReference.toDXN(toI).toString(),
+  strict: false,
+});