@dxos/assistant 0.8.3 → 0.8.4-main.1068cf700f

package/src/functions/services.ts

@@ -0,0 +1,187 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+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 type * as SchemaAST from 'effect/SchemaAST';
+
+import { AiToolNotFoundError, ToolExecutionService, ToolResolverService } from '@dxos/ai';
+import { todo } from '@dxos/debug';
+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`.
+ *  2. Functions in DB: query `FunctionType` by `key=id`; if found, deserialize and project to a tool
+ *     (propagating any `deployedFunctionId` discovered in the object's metadata).
+ *  3. Functions passed in: fall back to a matching `FunctionDefinition` from the `functions` array.
+ *
+ * If none of the above yield a match, the effect fails with `AiToolNotFoundError`.
+ *
+ * Requires `Database.Service` in the environment.
+ */
+export const makeToolResolverFromFunctions = (): Layer.Layer<
+  ToolResolverService,
+  never,
+  GenericToolkit.Provider | FunctionInvocationService
+> => {
+  return Layer.effect(
+    ToolResolverService,
+    Effect.gen(function* () {
+      const toolkitProvider = yield* GenericToolkit.Provider;
+      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 = (): Layer.Layer<
+  ToolExecutionService,
+  never,
+  FunctionInvocationService | GenericToolkit.Provider
+> => {
+  return Layer.effect(
+    ToolExecutionService,
+    Effect.gen(function* () {
+      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;
+
+      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 { definition: functionDef } = Context.get(FunctionToolAnnotation)(tool.annotations as any);
+
+              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 ToolExecutionServices = Layer.mergeAll(
+  makeToolResolverFromFunctions(),
+  makeToolExecutionServiceFromFunctions(),
+);
+
+class FunctionToolAnnotation extends Context.Tag('@dxos/assistant/FunctionToolAnnotation')<
+  FunctionToolAnnotation,
+  { definition: FunctionDefinition.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`).
+ */
+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),
+    // TODO(dmaretskyi): Include output schema.
+    failure: Schema.Any, // TODO(dmaretskyi): Better type for the failure?
+  }).annotate(FunctionToolAnnotation, { definition: fn });
+  toolCache.set(fn, tool);
+  return tool;
+};
+
+/**
+ * @returns Tool name produced from function name by escaping invalid characters.
+ */
+const makeToolName = (name: string) => {
+  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>> => {
+  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}`);
+  }
+};
+
+/**
+ * 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/index.ts

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

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);

package/src/session/artifact-diff.ts

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

package/src/session/error-handling.ts

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

package/src/session/format.test.ts

@@ -0,0 +1,124 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { Blueprint, Template } from '@dxos/blueprints';
+import { Database, Obj, Query } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { defineFunction } from '@dxos/functions';
+import { Text } from '@dxos/schema';
+import { Organization } from '@dxos/types';
+import { trim } from '@dxos/util';
+
+import { createSystemPrompt } from '../templates/system';
+import { AssistantTestLayer } from '../testing';
+
+import { formatSystemPrompt } from './format';
+
+const organizationListFunction = defineFunction({
+  key: 'dxos.org/function/organization-list',
+  name: 'Organization List',
+  description: 'List organizations',
+  inputSchema: Schema.Struct({}),
+  outputSchema: Schema.Array(Schema.String),
+  handler: Effect.fnUntraced(function* () {
+    const organizations = yield* Database.runQuery(Query.type(Organization.Organization));
+    return organizations.map((organization) => organization.name);
+  }),
+});
+
+const TestLayer = AssistantTestLayer({
+  types: [Text.Text, Organization.Organization, Blueprint.Blueprint],
+  functions: [organizationListFunction],
+});
+
+describe('format', () => {
+  it.effect(
+    'should format',
+    Effect.fnUntraced(
+      function* (_) {
+        const { db } = yield* Database.Service;
+        const object = db.add(
+          Obj.make(Organization.Organization, {
+            name: 'Test',
+            website: 'https://www.test.com',
+          }),
+        );
+
+        const blueprint = db.add(
+          Blueprint.make({
+            key: 'example.com/blueprint/test',
+            name: 'Test',
+            instructions: Template.make({
+              source: trim`
+                Test
+                This is the test blueprint.
+              `,
+            }),
+          }),
+        );
+
+        const output = yield* formatSystemPrompt({
+          system: createSystemPrompt({}),
+          blueprints: [blueprint],
+          objects: [object],
+        });
+
+        console.log(output);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.effect(
+    'should format with function input',
+    Effect.fnUntraced(
+      function* (_) {
+        const { db } = yield* Database.Service;
+        const object = db.add(
+          Obj.make(Organization.Organization, {
+            name: 'Test Org',
+            website: 'https://www.test.com',
+          }),
+        );
+
+        const blueprint = db.add(
+          Blueprint.make({
+            key: 'example.com/blueprint/test',
+            name: 'Test',
+            instructions: Template.make({
+              source: trim`
+                Organization List:
+                {{#each organizations}}
+                  - {{this}}
+                {{/each}}
+                `,
+              inputs: [
+                {
+                  name: 'organizations',
+                  kind: 'function',
+                  function: organizationListFunction.key,
+                },
+              ],
+            }),
+          }),
+        );
+
+        const output = yield* formatSystemPrompt({
+          system: createSystemPrompt({}),
+          blueprints: [blueprint],
+          objects: [object],
+        });
+
+        expect(output).to.include('Test Org');
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});