@dxos/assistant 0.8.4-main.f9ba587 → 0.8.4-main.fcc0d83b33

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/index.ts

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

package/src/functions/services.ts

@@ -0,0 +1,214 @@
+//
+// 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 Option from 'effect/Option';
+import * as Record from 'effect/Record';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { AiToolNotFoundError, ToolExecutionService, ToolResolverService } from '@dxos/ai';
+import { OpaqueToolkit } from '@dxos/ai';
+import { Operation, OperationRegistry } from '@dxos/compute';
+import { todo } from '@dxos/debug';
+import { Ref } from '@dxos/echo';
+import { invariant } from '@dxos/invariant';
+
+import { RefFromLLM } from '../types';
+
+export const makeToolResolverFromOperations = <R = never>({
+  toolkit: extraToolkit = OpaqueToolkit.empty,
+}: { toolkit?: OpaqueToolkit.OpaqueToolkit<never, never, R> } = {}): Layer.Layer<
+  ToolResolverService,
+  never,
+  OpaqueToolkit.OpaqueToolkitProvider | OperationRegistry.Service | R
+> => {
+  return Layer.effect(
+    ToolResolverService,
+    Effect.gen(function* () {
+      const toolkitProvider = yield* OpaqueToolkit.OpaqueToolkitProvider;
+      const operationRegistry = yield* OperationRegistry.Service;
+      return {
+        resolve: (id): Effect.Effect<Tool.Any, AiToolNotFoundError> =>
+          Effect.gen(function* () {
+            const toolkit = OpaqueToolkit.merge(extraToolkit, toolkitProvider.getToolkit());
+
+            const tool = toolkit.toolkit.tools[id];
+            if (tool) {
+              return tool;
+            }
+
+            return yield* operationRegistry.resolve(id).pipe(
+              Effect.flatMap(
+                Option.match({
+                  onSome: (_) => Effect.succeed(projectFunctionToTool(_)),
+                  onNone: () => Effect.fail(new AiToolNotFoundError(id)),
+                }),
+              ),
+            );
+          }),
+      } satisfies Context.Tag.Service<ToolResolverService>;
+    }),
+  );
+};
+
+export const makeToolExecutionService = <E, R>(opts: {
+  invoke: (tool: Tool.Any, input: unknown) => Effect.Effect<unknown>;
+}): Layer.Layer<ToolExecutionService, never, OpaqueToolkit.OpaqueToolkitProvider> =>
+  Layer.effect(
+    ToolExecutionService,
+    Effect.gen(function* () {
+      const toolkitProvider = yield* OpaqueToolkit.OpaqueToolkitProvider;
+      const toolkit = toolkitProvider.getToolkit();
+
+      const toolkitHandler = yield* toolkit.toolkit.pipe(Effect.provide(toolkit.layer));
+      invariant(isHandlerLike(toolkitHandler));
+
+      return {
+        handlersFor: (toolkit) => {
+          const makeHandler = (tool: 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 | OpaqueToolkit.OpaqueToolkitProvider
+> => {
+  return Layer.unwrapEffect(
+    Effect.gen(function* () {
+      const operationInvoker = yield* Operation.Service;
+
+      return makeToolExecutionService({
+        invoke: (tool, input) =>
+          Effect.gen(function* () {
+            const operationDef = getOperationFromTool(tool).pipe(Option.getOrThrow);
+
+            return yield* operationInvoker.invoke(operationDef, input).pipe(Effect.orDie);
+          }),
+      });
+    }),
+  );
+};
+
+export const ToolExecutionServices = Layer.mergeAll(
+  makeToolResolverFromOperations(),
+  makeToolExecutionServiceFromOperationInvoker(),
+);
+
+class FunctionToolAnnotation extends Context.Tag('@dxos/assistant/FunctionToolAnnotation')<
+  FunctionToolAnnotation,
+  { definition: Operation.Definition.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 = 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;
+};
+
+/**
+ * @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 (Ref.isRefType(ast)) {
+    const description = ast.annotations.description
+      ? ast.annotations.description + '\n' + RefFromLLM.ast.annotations.description
+      : (RefFromLLM.ast.annotations.description as string);
+    return RefFromLLM.annotations({ description }).ast;
+  } else if (SchemaAST.isTupleType(ast)) {
+    return new SchemaAST.TupleType(
+      ast.elements.map((t) => new SchemaAST.OptionalType(mapSchemaTypeForLLM(t.type), t.isOptional, t.annotations)),
+      ast.rest.map((t) => new SchemaAST.Type(mapSchemaTypeForLLM(t.type), t.annotations)),
+      ast.isReadonly,
+      ast.annotations,
+    );
+  } else if (SchemaAST.isTypeLiteral(ast)) {
+    return new SchemaAST.TypeLiteral(
+      ast.propertySignatures.map(
+        (p) =>
+          new SchemaAST.PropertySignature(
+            p.name,
+            mapSchemaTypeForLLM(p.type),
+            p.isOptional,
+            p.isReadonly,
+            p.annotations,
+          ),
+      ),
+      ast.indexSignatures,
+      ast.annotations,
+    );
+  }
+
+  return ast;
+};
+
+const isHandlerLike = (value: unknown): value is Toolkit.WithHandler<Record<string, Tool.Any>> => {
+  return typeof (value as any).tools === 'object' && typeof (value as any).handle === 'function';
+};

package/src/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_01RTYeojYbdVe9QGkcMvKbER","modelId":"claude-opus-4-6","timestamp":"1970-01-01T00:00:00.000Z","metadata":{}},{"type":"reasoning-start","id":"0","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"The","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" user wants to know the name of an organization with ID 01JGFJJZ00G0WKQSJGMAKCNT89.","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"","metadata":{"anthropic":{"type":"thinking","signature":"EpECClkIDRgCKkBhbbtJF+Q+wsAR8giXTK13Eui/M8yFfrB46Vzozj6aWeupuZy0FCx6VSI4FmNelVTGMCsbT5apFxxgVf6A7FAJMg9jbGF1ZGUtb3B1cy00LTY4ABIMHOEtEgcKz5Wb+gpbGgxPG+AOzUXWigifeyUiML7FnkmDoz8pWD5P9R4Wul/DeoJE41ntyU/B/abCz0pQx4PHE8N4i5aoFBhUuQE5hSpmlXcA03Cj9t8LvHSOwMobEUZcnKTZn9x1upUfts+Ez+NsQBXY//niKxqt/E7yE5TKHwDO/nuZ2rteTus79EjTEkPaEUcXQso8YAbQknG7ldRd1Nd2X4D2X+bBJH2AVG7SKLSFW3QAGAE="}}},{"type":"reasoning-end","id":"0","metadata":{}},{"type":"tool-params-start","id":"toolu_01KM7uhfLgRWepvTtotjHME2","name":"read-name","providerExecuted":false,"metadata":{}},{"type":"tool-params-delta","id":"toolu_01KM7uhfLgRWepvTtotjHME2","delta":"","metadata":{}},{"type":"tool-params-delta","id":"toolu_01KM7uhfLgRWepvTtotjHME2","delta":"{\"org\": \"01","metadata":{}},{"type":"tool-params-delta","id":"toolu_01KM7uhfLgRWepvTtotjHME2","delta":"JGFJJZ0","metadata":{}},{"type":"tool-params-delta","id":"toolu_01KM7uhfLgRWepvTtotjHME2","delta":"0G0W","metadata":{}},{"type":"tool-params-delta","id":"toolu_01KM7uhfLgRWepvTtotjHME2","delta":"KQSJGMAKCN","metadata":{}},{"type":"tool-params-delta","id":"toolu_01KM7uhfLgRWepvTtotjHME2","delta":"T89\"}","metadata":{}},{"type":"tool-params-end","id":"toolu_01KM7uhfLgRWepvTtotjHME2","metadata":{}},{"type":"finish","reason":"tool-calls","usage":{"inputTokens":883,"outputTokens":122,"totalTokens":1005},"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":883,"output_tokens":9,"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 wants to know the name of an organization with ID 01JGFJJZ00G0WKQSJGMAKCNT89.","options":{}},{"type":"tool-call","id":"toolu_01KM7uhfLgRWepvTtotjHME2","name":"read-name","params":{"org":"01JGFJJZ00G0WKQSJGMAKCNT89"},"providerExecuted":false,"options":{}}],"options":{}},{"role":"tool","content":[{"type":"tool-result","id":"toolu_01KM7uhfLgRWepvTtotjHME2","name":"read-name","isFailure":false,"result":"BlueYard","providerExecuted":false,"options":{}}],"options":{"anthropic":{"cacheControl":{"ttl":"5m","type":"ephemeral"}}}}]},"response":[{"type":"response-metadata","id":"msg_016RCVnGrLXVf4ba4KznSHyr","modelId":"claude-opus-4-6","timestamp":"1970-01-01T00:00:00.000Z","metadata":{}},{"type":"reasoning-start","id":"0","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"The","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" name of the organization is \"BlueYard\".","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"","metadata":{"anthropic":{"type":"thinking","signature":"EuYBClkIDRgCKkA0n2vPrvDwpmiAgWX5raN/PW8EkSgAqlMsO4gsgxIXidyUWiozI8lhzJTYOm5D3BOTMcW+mcfUvAw1rtDVianiMg9jbGF1ZGUtb3B1cy00LTY4ABIMiAi8SSliRognm8yNGgx+gpH0kejwSoiouLAiMBy9umHrGuQCJ92KaaBqRAq50lt7WXRaCyO3vuheveWN1JDryUFhh7GUZ/pogH0m+Co7lZSQmO4ybaE4MmyYbu7S3e/upJcsrQIiMB7LByFcpfSrjsF/VSIPprW5kMMafV1yQ6U2uI+dhUTohKMYAQ=="}}},{"type":"reasoning-end","id":"0","metadata":{}},{"type":"text-start","id":"1","metadata":{}},{"type":"text-delta","id":"1","delta":"The name of the organization with ID `01JGFJJZ00G0WKQSJGMAKCNT89` is","metadata":{}},{"type":"text-delta","id":"1","delta":" **BlueYard**.","metadata":{}},{"type":"text-end","id":"1","metadata":{}},{"type":"finish","reason":"stop","usage":{"inputTokens":973,"outputTokens":66,"totalTokens":1039},"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":973,"output_tokens":8,"server_tool_use":null,"service_tier":"standard"}}}}]}]}

package/src/index.ts

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

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.ts

@@ -0,0 +1,149 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Function from 'effect/Function';
+import * as Option from 'effect/Option';
+
+import { Template } from '@dxos/compute';
+import { type FunctionNotFoundError } from '@dxos/compute';
+import { type Operation, type OperationRegistry } from '@dxos/compute';
+import { type Database, Obj } from '@dxos/echo';
+import { ObjectVersion } from '@dxos/echo-db';
+import type { ObjectNotFoundError } from '@dxos/echo/Err';
+import { type ObjectId } from '@dxos/keys';
+import { log } from '@dxos/log';
+import { type ContentBlock, Message } from '@dxos/types';
+import { trim } from '@dxos/util';
+
+import { AiAssistantError } from '../errors';
+import { ArtifactDiffResolver } from './artifact-diff';
+import { type AiRequestRunError, type AiRequestRunProps } from './request';
+
+/**
+ * Formats the system prompt.
+ */
+// TODO(burdon): Move to AiPreprocessor.
+export const formatSystemPrompt = ({
+  system,
+  blueprints = [],
+  objects = [],
+}: Pick<AiRequestRunProps, 'system' | 'blueprints' | 'objects'>): Effect.Effect<
+  string,
+  FunctionNotFoundError | ObjectNotFoundError,
+  Database.Service | OperationRegistry.Service | Operation.Service
+> =>
+  Effect.gen(function* () {
+    const blueprintDefs = yield* Function.pipe(
+      blueprints,
+      Effect.forEach((blueprint) => Effect.succeed(blueprint.instructions)),
+      Effect.flatMap(
+        Effect.forEach((template) =>
+          Effect.gen(function* () {
+            return trim`
+            <blueprint>
+              ${yield* Template.processTemplate(template)}
+            </blueprint>
+          `;
+          }),
+        ),
+      ),
+      Effect.map((blueprints) =>
+        blueprints.length > 0 ? ['## Blueprints Definitions', ...blueprints].join('\n\n') : undefined,
+      ),
+    );
+
+    const objectDefs = yield* Function.pipe(
+      objects,
+      Effect.forEach((object) =>
+        Effect.succeed(trim`
+          <object>
+            <dxn>${Obj.getDXN(object)}</dxn>
+            <typename>${Obj.getTypename(object)}</typename>
+          </object>
+        `),
+      ),
+      Effect.map((objects) => (objects.length > 0 ? ['## Context Objects', ...objects].join('\n\n') : undefined)),
+    );
+
+    return yield* Function.pipe(
+      Effect.succeed([system, blueprintDefs, objectDefs].filter((def): def is string => def !== undefined)),
+      Effect.map((parts) => parts.join('\n\n')),
+    );
+  }).pipe(Effect.withSpan('formatSystemPrompt'));
+
+/**
+ * Formats the user prompt.
+ */
+// TODO(burdon): Move to AiPreprocessor.
+// TODO(burdon): Convert util below to `Effect.fn` (to preserve stack info)
+export const formatUserPrompt = ({
+  prompt,
+  history = [],
+}: Pick<AiRequestRunProps, 'prompt' | 'history'>): Effect.Effect<Message.Message, AiRequestRunError> =>
+  Effect.gen(function* () {
+    const blocks: ContentBlock.Any[] = [];
+
+    // TODO(dmaretskyi): Evaluate other approaches as `serviceOption` isn't represented in the type system.
+    const artifactDiffResolver = yield* Effect.serviceOption(ArtifactDiffResolver);
+    if (Option.isSome(artifactDiffResolver)) {
+      const versions = gatherObjectVersions(history);
+      const artifactDiff = yield* Effect.tryPromise({
+        try: () =>
+          artifactDiffResolver.value.resolve(
+            [...versions.entries()].map(([id, version]) => ({ id, lastVersion: version })),
+          ),
+        catch: AiAssistantError.wrap({ message: 'Artifact diff resolution error' }),
+      });
+
+      log('version', { artifactDiff, versions });
+      for (const [id, { version }] of [...artifactDiff.entries()]) {
+        if (ObjectVersion.equals(version, versions.get(id)!)) {
+          artifactDiff.delete(id);
+          continue;
+        }
+
+        blocks.push({ _tag: 'anchor', objectId: id, version });
+      }
+
+      if (artifactDiff.size > 0) {
+        blocks.push(createArtifactUpdateBlock(artifactDiff));
+      }
+    }
+
+    return Obj.make(Message.Message, {
+      created: new Date().toISOString(),
+      sender: { role: 'user' },
+      blocks: typeof prompt === 'string' ? [...blocks, { _tag: 'text', text: prompt }] : [...blocks, ...prompt],
+    });
+  }).pipe(Effect.withSpan('formatUserPrompt'));
+
+const gatherObjectVersions = (messages: Message.Message[]): Map<ObjectId, ObjectVersion> => {
+  const artifactIds = new Map<ObjectId, ObjectVersion>();
+  for (const message of messages) {
+    for (const block of message.blocks) {
+      if (block._tag === 'anchor') {
+        artifactIds.set(block.objectId, block.version as ObjectVersion);
+      }
+    }
+  }
+
+  return artifactIds;
+};
+
+const createArtifactUpdateBlock = (
+  artifactDiff: Map<ObjectId, { version: ObjectVersion; diff?: string }>,
+): ContentBlock.Any => {
+  return {
+    _tag: 'text',
+    // TODO(dmaretskyi): Does this need to be a special content-block?
+    disposition: 'synthetic',
+    text: trim`
+      The following artifacts have been updated since the last message:
+      ${[...artifactDiff.entries()]
+        .map(([id, { diff }]) => `<changed-artifact id="${id}">${diff ? `\n${diff}` : ''}</changed-artifact>`)
+        .join('\n')}
+    `,
+  };
+};

package/src/session/index.ts

@@ -2,5 +2,9 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './session';
+export * from './artifact-diff';
+export * from './observer';
+export * from './request';
+export * from './toolkit';
 export * from './version-pin';
+export * from './format';

package/src/session/observer.ts

@@ -0,0 +1,62 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Tool from '@effect/ai/Tool';
+import * as Effect from 'effect/Effect';
+import * as Function from 'effect/Function';
+
+import { type AiParser, type ConsolePrinter } from '@dxos/ai';
+import { type Message } from '@dxos/types';
+
+/**
+ * Live observer of the generation process.
+ */
+export interface GenerationObserver<
+  Tools extends Record<string, Tool.Any> = any,
+> extends AiParser.ParseResponseCallbacks<Tools> {
+  /**
+   * Complete messages fired during the session, both from the model and from the user.
+   * This message will contain all message blocks emitted through the `onBlock` callback.
+   */
+  onMessage: (message: Message.Message) => Effect.Effect<void>;
+}
+
+export const GenerationObserver = Object.freeze({
+  make: ({
+    onBegin = Function.constant(Effect.void),
+    onPart = Function.constant(Effect.void),
+    onBlock = Function.constant(Effect.void),
+    onEnd = Function.constant(Effect.void),
+    onMessage = Function.constant(Effect.void),
+  }: Partial<GenerationObserver> = {}): GenerationObserver => ({
+    onBegin,
+    onPart,
+    onBlock,
+    onEnd,
+    onMessage,
+  }),
+
+  noop: () => GenerationObserver.make(),
+
+  /**
+   * Debug printer to be used in unit-tests and browser devtools.
+   */
+  fromPrinter: (printer: ConsolePrinter) =>
+    GenerationObserver.make({
+      onBlock: (block) =>
+        Effect.sync(() => {
+          if (block.pending) {
+            return; // Only prints full blocks (better for unit-tests and browser devtools).
+          }
+          printer.printContentBlock(block);
+        }),
+      onMessage: (message) =>
+        Effect.sync(() => {
+          if (message.sender.role === 'assistant') {
+            return; // Skip assistant messages since they are printed in the `onBlock` callback.
+          }
+          printer.printMessage(message);
+        }),
+    }),
+});