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

package/src/testing/layer.ts

@@ -2,77 +2,262 @@
 // Copyright 2026 DXOS.org
 //
 
+import { Registry } from '@effect-atom/atom';
 import * as Layer from 'effect/Layer';
 import * as Match from 'effect/Match';
 
-import { AiService, type ModelName } from '@dxos/ai';
+import {
+  AiService,
+  ConsolePrinter,
+  GenericToolkit,
+  type ModelName,
+  type ToolExecutionService,
+  type ToolResolverService,
+} 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 { Database, DXN, Feed, Type } from '@dxos/echo';
+import { acquireReleaseResource } from '@dxos/effect';
+import {
+  CredentialsService,
+  FunctionInvocationService,
+  QueueService,
+  type ServiceCredential,
+  ServiceNotAvailableError,
+  Trace,
+  TracingService,
+} from '@dxos/functions';
+import {
+  Process,
+  ProcessManager,
+  ServiceResolver,
+  TracingServiceExt,
+  TriggerDispatcher,
+  TriggerStateStore,
+} from '@dxos/functions-runtime';
 import { FunctionInvocationServiceLayerTest, TestDatabaseLayer } from '@dxos/functions-runtime/testing';
+import { Message } from '@dxos/types';
 
-import { makeToolExecutionServiceFromFunctions, makeToolResolverFromFunctions } from '../functions';
-import { GenericToolkit } from '../session';
+import { Blueprint, Prompt } from '@dxos/blueprints';
+import { Operation, OperationHandlerSet, OperationRegistry } from '@dxos/operation';
+import * as LanguageModel from '@effect/ai/LanguageModel';
+import * as KeyValueStore from '@effect/platform/KeyValueStore';
+import { ToolExecutionServices } from '../functions';
+import { AgentService } from '../service';
+
+import type { TestContextService } from '@dxos/effect/testing';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import {
+  AiContextBinder,
+  AiContextService,
+  AiConversation,
+  AiConversationService,
+  type ContextBinding,
+} from '../conversation';
+import * as Array from 'effect/Array';
+import { CompleteBlock } from '../tracing';
 
 interface TestLayerOptions {
   aiServicePreset?: 'direct' | 'edge-local' | 'edge-remote';
   model?: ModelName;
-  functions?: FunctionDefinition.Any[];
+  operationHandlers?: OperationHandlerSet.OperationHandlerSet | OperationHandlerSet.OperationHandlerSet[];
   toolkits?: GenericToolkit.GenericToolkit[];
-  types?: Type.Entity.Any[];
+  types?: Type.AnyEntity[];
+  blueprints?: Blueprint.Blueprint[];
   credentials?: ServiceCredential[];
   /*
    * Tracing configuration.
    * @default 'noop'
    */
   tracing?: 'noop' | 'console' | 'pretty';
+
+  disableLlmMemoization?: boolean;
+
+  /**
+   * Core system prompt for the agent.
+   */
+  systemPrompt?: string;
 }
 
+export type AssistantTestServices =
+  // Convinience
+  | LanguageModel.LanguageModel
+  | Feed.Service
+  | CredentialsService
+  | AgentService.AgentService
+  | AiService.AiService
+  | Database.Service
+  | QueueService
+  // Registries
+  | Blueprint.RegistryService
+  | OperationRegistry.Service
+  | GenericToolkit.GenericToolkitProvider
+  // Core
+  | ProcessManager.ProcessManagerService
+  | Process.ProcessMonitorService
+  | Registry.AtomRegistry
+  // Should those be here?
+  | OperationHandlerSet.OperationHandlerProvider
+  | KeyValueStore.KeyValueStore
+  | ServiceResolver.ServiceResolver
+  | TracingService
+  | Trace.TraceService
+  | Trace.TraceSink
+  // Deperacted
+  | ToolExecutionService
+  | ToolResolverService
+  | FunctionInvocationService;
+
 export const AssistantTestLayer = ({
   aiServicePreset = 'direct',
-  model = '@anthropic/claude-opus-4-0',
-  functions = [],
+  model = '@anthropic/claude-opus-4-6',
+  operationHandlers = [],
   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,
+  disableLlmMemoization = false,
+  blueprints = [],
+  systemPrompt,
+}: TestLayerOptions = {}): Layer.Layer<AssistantTestServices, never, TestContextService> => {
+  const toolkit = GenericToolkit.merge(...toolkits);
+  const operationHandlersSet = Array.isArray(operationHandlers)
+    ? OperationHandlerSet.merge(...operationHandlers)
+    : operationHandlers;
+  types.push(Blueprint.Blueprint, Prompt.Prompt, Operation.PersistentOperation, Feed.Feed);
+  types = Array.dedupeWith(types, (a, b) => Type.getTypename(a) === Type.getTypename(b));
+
+  return Layer.empty.pipe(
+    Layer.provideMerge(Trace.testTraceService({ meta: { processName: 'test' } })),
+    Layer.provideMerge(AgentService.layer({ systemPrompt })),
+    Layer.provideMerge(ProcessManager.layer({ idGenerator: ProcessManager.SequentialProcessIdGenerator })),
+    Layer.provideMerge(
+      // TODO(dmaretskyi): Refactor to be able to merge resovler layers, also consider service mesh achitecture.
+      Layer.effect(
+        ServiceResolver.ServiceResolver,
+        Effect.gen(function* () {
+          const services = yield* Effect.context<Database.Service | QueueService>().pipe(
+            Effect.map(Context.pick(Database.Service, QueueService)),
+            Effect.map(Layer.succeedContext),
+          );
+          // AiContextBinder.
+          return ServiceResolver.compose(
+            ServiceResolver.succeed(AiContextService, (context) =>
+              Effect.gen(function* () {
+                if (!context.conversation) {
+                  return yield* Effect.fail(new ServiceNotAvailableError(AiContextService.key));
+                }
+                const feed = yield* Database.resolve(DXN.parse(context.conversation), Feed.Feed).pipe(Effect.orDie);
+                const queue = yield* QueueService.getQueue(Feed.getQueueDxn(feed)!);
+                const binder = yield* acquireReleaseResource(
+                  () =>
+                    new AiContextBinder({
+                      queue,
+                    }),
+                );
+                return { binder };
+              }).pipe(Effect.provide(services)),
+            ),
+            // AiConversationService.
+            ServiceResolver.succeed(AiConversationService, (context) =>
+              Effect.gen(function* () {
+                if (!context.conversation) {
+                  return yield* Effect.fail(new ServiceNotAvailableError(AiContextService.key));
+                }
+                const feed = yield* Database.resolve(DXN.parse(context.conversation), Feed.Feed).pipe(Effect.orDie);
+                const queue = yield* QueueService.getQueue<ContextBinding | Message.Message>(Feed.getQueueDxn(feed)!);
+                const conversation = yield* acquireReleaseResource(
+                  () =>
+                    new AiConversation({
+                      queue,
+                    }),
+                );
+                return conversation;
+              }).pipe(Effect.provide(services)),
+            ),
+            yield* ServiceResolver.fromRequirements(
+              Database.Service,
+              GenericToolkit.GenericToolkitProvider,
+              QueueService,
+              AiService.AiService,
+              OperationRegistry.Service,
+              Blueprint.RegistryService,
+              FunctionInvocationService,
+            ),
+          );
+        }),
+      ),
     ),
-  ).pipe(
+    Layer.provideMerge(Layer.mergeAll(OperationRegistry.layer, AiService.model(model), ToolExecutionServices)),
     Layer.provideMerge(
       FunctionInvocationServiceLayerTest({
-        functions,
+        functions: operationHandlersSet,
       }),
     ),
     Layer.provideMerge(
       Layer.mergeAll(
-        TestAiService({ preset: aiServicePreset }),
+        TestAiService({ preset: aiServicePreset, disableMemoization: disableLlmMemoization }),
         TestDatabaseLayer({
           spaceKey: 'fixed',
           types,
         }),
         CredentialsService.configuredLayer(credentials),
+        Feed.notAvailable,
         Match.value(tracing).pipe(
           Match.when('noop', () => TracingService.layerNoop),
           Match.when('console', () => TracingServiceExt.layerLogInfo()),
-          Match.when('pretty', () => TracingServiceExt.layerConsolePrettyPrint()),
+          Match.when('pretty', () =>
+            TracingServiceExt.layerConsolePrettyPrint({
+              toolkit: (toolkits.length > 0 ? GenericToolkit.merge(...toolkits) : GenericToolkit.empty).toolkit as any,
+            }),
+          ),
+          Match.exhaustive,
+        ),
+        Match.value(tracing).pipe(
+          Match.when('noop', () => Trace.layerNoop),
+          Match.when('console', () => Trace.layerConsole),
+          Match.when('pretty', () => TraceSinkPretty()),
           Match.exhaustive,
         ),
       ),
     ),
+    Layer.provideMerge(Layer.succeed(Blueprint.RegistryService, new Blueprint.Registry(blueprints))),
+    Layer.provideMerge(GenericToolkit.providerLayer(toolkit)),
+    Layer.provideMerge(OperationHandlerSet.provide(operationHandlersSet)),
+    Layer.provideMerge(KeyValueStore.layerMemory),
+    Layer.provideMerge(Registry.layer),
+    Layer.orDie,
   );
+};
 
 interface TestLayerWithTriggersOptions extends TestLayerOptions {}
 
-export const AssistantTestLayerWithTriggers = (options: TestLayerWithTriggersOptions) =>
+export type AssistantTestServicesWithTriggers = AssistantTestServices | TriggerDispatcher | TriggerStateStore;
+
+export const AssistantTestLayerWithTriggers = (
+  options: TestLayerWithTriggersOptions,
+): Layer.Layer<AssistantTestServicesWithTriggers, never, TestContextService> =>
   Layer.mergeAll(
     AssistantTestLayer(options),
-    TriggerDispatcher.layer({ timeControl: 'manual', startingTime: new Date('2025-09-05T15:01:00.000Z') }),
-  ).pipe(Layer.provideMerge(TriggerStateStore.layerMemory));
+    TriggerDispatcher.layer({ timeControl: 'manual', startingTime: new Date('2025-09-05T15:01:00.000Z') }).pipe(
+      Layer.provide(Registry.layer),
+    ),
+    TriggerStateStore.layerMemory,
+  ) as any;
+
+const TraceSinkPretty = () =>
+  Layer.succeed(Trace.TraceSink, {
+    write: (message) => {
+      for (const event of message.events) {
+        if (Trace.isOfType(CompleteBlock, event)) {
+          const tag = message.meta.processName ?? `[${message.meta.pid ?? 'unknown'}]`;
+          console.log(`[${tag}] ${event.data.role.toUpperCase()}`);
+          new ConsolePrinter({ tag }).printContentBlock(event.data.block);
+        } else if (Trace.isOfType(Process.SpawnedEvent, event)) {
+          console.log(`[${message.meta.pid}] Process spawned: ${message.meta.processName}`);
+        } else if (Trace.isOfType(Process.ExitedEvent, event)) {
+          console.log(`[${message.meta.pid}] Process exited: ${event.data.outcome}`);
+        }
+      }
+    },
+  });

package/src/tracing.ts

@@ -0,0 +1,112 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Trace } from '@dxos/functions';
+import { Obj } from '@dxos/echo';
+import { ContentBlock, Actor } from '@dxos/types';
+import * as Schema from 'effect/Schema';
+
+/**
+ * Partial content block emitted.
+ */
+export const PartialBlock = Trace.EventType('assistant.partialBlock', {
+  schema: Schema.Struct({
+    messageId: Obj.ID,
+    role: Actor.Role,
+    block: ContentBlock.Any,
+  }),
+  isEphemeral: true,
+});
+
+/**
+ * Complete content block emitted.
+ */
+export const CompleteBlock = Trace.EventType('assistant.completeBlock', {
+  schema: Schema.Struct({
+    messageId: Obj.ID,
+    role: Actor.Role,
+    block: ContentBlock.Any,
+  }),
+  isEphemeral: false,
+});
+
+/**
+ * Agent turn started (one LLM generation cycle).
+ */
+export const AgentTurnStarted = Trace.EventType('assistant.agentTurnStarted', {
+  schema: Schema.Struct({
+    /** Number of history messages. */
+    historyLength: Schema.Number,
+    /** Number of pending messages. */
+    pendingLength: Schema.Number,
+    /** System prompt length in characters. */
+    systemPromptLength: Schema.Number,
+  }),
+  isEphemeral: false,
+});
+
+/**
+ * Agent turn completed (LLM response received).
+ */
+export const AgentTurnCompleted = Trace.EventType('assistant.agentTurnCompleted', {
+  schema: Schema.Struct({
+    /** Number of messages produced in this turn. */
+    messageCount: Schema.Number,
+    /** Whether the agent is done (no more tool calls). */
+    done: Schema.Boolean,
+  }),
+  isEphemeral: false,
+});
+
+/**
+ * Tool execution started.
+ */
+export const ToolCallStarted = Trace.EventType('assistant.toolCallStarted', {
+  schema: Schema.Struct({
+    /** Tool name. */
+    name: Schema.String,
+    /** Tool call ID. */
+    toolCallId: Schema.String,
+  }),
+  isEphemeral: false,
+});
+
+/**
+ * Tool execution completed.
+ */
+export const ToolCallCompleted = Trace.EventType('assistant.toolCallCompleted', {
+  schema: Schema.Struct({
+    /** Tool name. */
+    name: Schema.String,
+    /** Tool call ID. */
+    toolCallId: Schema.String,
+    /** Whether the tool call resulted in an error. */
+    isError: Schema.Boolean,
+  }),
+  isEphemeral: false,
+});
+
+/**
+ * Agent process received input (prompt or tool result).
+ */
+export const AgentInputReceived = Trace.EventType('assistant.agentInputReceived', {
+  schema: Schema.Struct({
+    /** Type of input: 'prompt' or 'tool_result'. */
+    inputType: Schema.String,
+    /** Length of input content. */
+    contentLength: Schema.Number,
+  }),
+  isEphemeral: false,
+});
+
+/**
+ * Agent process request completed.
+ */
+export const AgentRequestCompleted = Trace.EventType('assistant.agentRequestCompleted', {
+  schema: Schema.Struct({
+    /** Number of pending items remaining in queue. */
+    pendingItems: Schema.Number,
+  }),
+  isEphemeral: false,
+});

package/src/types/artifact.ts

@@ -5,7 +5,7 @@
 import type * as Effect from 'effect/Effect';
 import * as Schema from 'effect/Schema';
 
-import { type Err, Type } from '@dxos/echo';
+import { type Err, Obj, Ref, type 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';
@@ -16,16 +16,16 @@ import { trim } from '@dxos/util';
  */
 export const createArtifactElement = (id: ObjectId) => `<artifact id=${id} />`;
 
+// TODO(burdon): Rename RefFromLLM? -- yes -dm
 /**
  * A model-friendly way to reference an object.
  * Supports vairous formats that will be normalized to a DXN.
  *
- * @deprecated Use `RefFromLLM` instead.
+ * @deprecated Use `Ref.Ref(XXX)` instead.
  */
-// TODO(burdon): Rename RefFromLLM? -- yes -dm
 export const ArtifactId: Schema.Schema<string> & {
   toDXN: (reference: ArtifactId, owningSpaceId?: SpaceId) => DXN;
-  resolve: <S extends Type.Entity.Any>(
+  resolve: <S extends Type.AnyEntity>(
     schema: S,
     ref: ArtifactId,
   ) => Effect.Effect<Schema.Schema.Type<S>, Err.ObjectNotFoundError, Database.Service>;
@@ -33,11 +33,16 @@ export const ArtifactId: Schema.Schema<string> & {
   // TODO(dmaretskyi): This section gets overriden.
   description: trim`
     The ID of the referenced object. Formats accepted:
-    - DXN (dxn:echo:@:XXXXX). DXNs can be prepended with an @ symbol for compatibility with in-text references.
+    - DXN (dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4). DXNs can be prepended with an @ symbol for compatibility with in-text references.
     - space ID, object ID tuple (spaceID:objectID)
-    - Only object ID that is assumed to be in the current space (XXXXX)
+    - Only object ID that is assumed to be in the current space (01KG7R1ZXWFMWQ4DA1Q6TN1DG4)
   `,
-  examples: ['dxn:echo:@:XXXXX', '@dxn:echo:@:XXXXX', 'spaceID:objectID', 'XXXXX'],
+  examples: [
+    'dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+    '@dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+    'BM3FSHFOMJCHCG5QW7JTVKGYABD2GAA7G:01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+    '01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+  ],
 }) {
   static toDXN(reference: ArtifactId, owningSpaceId?: SpaceId): DXN {
     // Allow @dxn: prefix for compatibility with in-text references.
@@ -61,12 +66,12 @@ export const ArtifactId: Schema.Schema<string> & {
   /**
    * Resolves an artifact ID to an object.
    */
-  static resolve<S extends Type.Entity.Any>(
+  static resolve<S extends Type.AnyEntity>(
     schema: S,
     ref: ArtifactId,
   ): Effect.Effect<Schema.Schema.Type<S>, Err.ObjectNotFoundError, Database.Service> {
     const dxn = ArtifactId.toDXN(ref);
-    return Database.Service.resolve(dxn, schema);
+    return Database.resolve(dxn, schema);
   }
 };
 
@@ -75,8 +80,10 @@ 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), {
+export const RefFromLLM = Schema.transform(ArtifactId, Ref.Ref(Obj.Unknown), {
   decode: (fromA, fromI) => EncodedReference.fromDXN(ArtifactId.toDXN(fromA)),
   encode: (toI, toA) => EncodedReference.toDXN(toI).toString(),
   strict: false,
+}).annotations({
+  description: ArtifactId.ast.annotations.description as string,
 });