@dxos/agent-runtime 0.0.0

package/src/functions.conversations.json

@@ -0,0 +1 @@
+{"conversations":[{"parameters":{"model":"dxn:com.anthropic.model.claude-opus-4-8.default","stream":true,"tools":[{"name":"read-name","description":"Reads the name of an organization.","inputSchema":{"type":"object","required":["org"],"properties":{"org":{"type":"string","description":"The URI of the referenced object. Protocols accepted:\n- echo://01KG7R1ZXWFMWQ4DA1Q6TN1DG4. \n- space ID, object ID tuple (spaceID:objectID)\n- Only object ID that is assumed to be in the current space (01KG7R1ZXWFMWQ4DA1Q6TN1DG4)\n- dxn:org.dxos.type.calendar:0.1.0 -- named entity from the registry. Absoutely make sure it actually exists in the registry.\n\nURIs can be prepended with an @ symbol for compatibility with in-text references.","examples":["echo://01KG7R1ZXWFMWQ4DA1Q6TN1DG4","@echo://01KG7R1ZXWFMWQ4DA1Q6TN1DG4","BM3FSHFOMJCHCG5QW7JTVKGYABD2GAA7G:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","01KG7R1ZXWFMWQ4DA1Q6TN1DG4","dxn:org.dxos.type.calendar:0.1.0","@dxn:org.dxos.type.calendar:0.1.0"]}},"additionalProperties":false}}]},"prompt":{"content":[{"role":"user","content":"What is the name of the organization? 01JGFJJZ00G0WKQSJGMAKCNT8A","options":{"anthropic":{"cacheControl":{"ttl":"5m","type":"ephemeral"}}}}]},"response":[{"type":"response-metadata","id":"msg_01QqqhNhmhVZUUYXFYx9XMtH","modelId":"claude-opus-4-8","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 look up the name of that organization for you.","metadata":{}},{"type":"text-end","id":"0","metadata":{}},{"type":"tool-params-start","id":"toolu_01SSt4imayWykNwg78gTArrk","name":"read-name","providerExecuted":false,"metadata":{}},{"type":"tool-params-delta","id":"toolu_01SSt4imayWykNwg78gTArrk","delta":"","metadata":{}},{"type":"tool-params-delta","id":"toolu_01SSt4imayWykNwg78gTArrk","delta":"{\"o","metadata":{}},{"type":"tool-params-delta","id":"toolu_01SSt4imayWykNwg78gTArrk","delta":"rg\": \"01J","metadata":{}},{"type":"tool-params-delta","id":"toolu_01SSt4imayWykNwg78gTArrk","delta":"GFJJZ00G","metadata":{}},{"type":"tool-params-delta","id":"toolu_01SSt4imayWykNwg78gTArrk","delta":"0WKQSJGMA","metadata":{}},{"type":"tool-params-delta","id":"toolu_01SSt4imayWykNwg78gTArrk","delta":"KCNT8A\"}","metadata":{}},{"type":"tool-params-end","id":"toolu_01SSt4imayWykNwg78gTArrk","metadata":{}},{"type":"finish","reason":"tool-calls","usage":{"inputTokens":838,"outputTokens":86,"totalTokens":924},"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":838,"output_tokens":1,"server_tool_use":null,"service_tier":"standard"}}}}]},{"parameters":{"model":"dxn:com.anthropic.model.claude-opus-4-8.default","stream":true,"tools":[{"name":"read-name","description":"Reads the name of an organization.","inputSchema":{"type":"object","required":["org"],"properties":{"org":{"type":"string","description":"The URI of the referenced object. Protocols accepted:\n- echo://01KG7R1ZXWFMWQ4DA1Q6TN1DG4. \n- space ID, object ID tuple (spaceID:objectID)\n- Only object ID that is assumed to be in the current space (01KG7R1ZXWFMWQ4DA1Q6TN1DG4)\n- dxn:org.dxos.type.calendar:0.1.0 -- named entity from the registry. Absoutely make sure it actually exists in the registry.\n\nURIs can be prepended with an @ symbol for compatibility with in-text references.","examples":["echo://01KG7R1ZXWFMWQ4DA1Q6TN1DG4","@echo://01KG7R1ZXWFMWQ4DA1Q6TN1DG4","BM3FSHFOMJCHCG5QW7JTVKGYABD2GAA7G:01KG7R1ZXWFMWQ4DA1Q6TN1DG4","01KG7R1ZXWFMWQ4DA1Q6TN1DG4","dxn:org.dxos.type.calendar:0.1.0","@dxn:org.dxos.type.calendar:0.1.0"]}},"additionalProperties":false}}]},"prompt":{"content":[{"role":"user","content":"What is the name of the organization? 01JGFJJZ00G0WKQSJGMAKCNT8A","options":{}},{"role":"assistant","content":[{"type":"text","text":"I'll look up the name of that organization for you.","options":{}},{"type":"tool-call","id":"toolu_01SSt4imayWykNwg78gTArrk","name":"read-name","params":{"org":"01JGFJJZ00G0WKQSJGMAKCNT8A"},"providerExecuted":false,"options":{}}],"options":{}},{"role":"tool","content":[{"type":"tool-result","id":"toolu_01SSt4imayWykNwg78gTArrk","name":"read-name","isFailure":false,"result":"BlueYard","providerExecuted":false,"options":{}}],"options":{"anthropic":{"cacheControl":{"ttl":"5m","type":"ephemeral"}}}}]},"response":[{"type":"response-metadata","id":"msg_01GzzfDTuyW585TBj6Yzz4Lv","modelId":"claude-opus-4-8","timestamp":"1970-01-01T00:00:00.000Z","metadata":{}},{"type":"text-start","id":"0","metadata":{}},{"type":"text-delta","id":"0","delta":"The","metadata":{}},{"type":"text-delta","id":"0","delta":" name of the organization is **BlueYard**.","metadata":{}},{"type":"text-end","id":"0","metadata":{}},{"type":"finish","reason":"stop","usage":{"inputTokens":936,"outputTokens":17,"totalTokens":953},"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":936,"output_tokens":1,"server_tool_use":null,"service_tier":"standard"}}}}]}]}

package/src/functions.test.ts

@@ -0,0 +1,87 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Schema from 'effect/Schema';
+
+import { ConsolePrinter } from '@dxos/ai';
+import { MemoizedAiService } from '@dxos/ai/testing';
+import { AiRequest, GenerationObserver, ToolExecutionServices, createToolkit } from '@dxos/assistant';
+import { Operation, OperationHandlerSet, Skill } from '@dxos/compute';
+import { Database, Obj, Ref } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { DXN, EntityId } from '@dxos/keys';
+import { Organization } from '@dxos/types';
+
+import { AssistantTestLayer } from './testing';
+
+EntityId.dangerouslyDisableRandomness();
+
+const ReadName = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.function.readName'),
+    name: 'Read Name',
+    description: 'Reads the name of an organization.',
+  },
+  input: Schema.Struct({
+    org: Ref.Ref(Organization.Organization),
+  }),
+  output: Schema.String,
+  services: [Database.Service],
+});
+
+const Handlers = OperationHandlerSet.make(
+  Operation.withHandler(
+    ReadName,
+    Effect.fn(function* ({ org }) {
+      const resolved = yield* Database.load(org);
+      return resolved.name ?? '<no org>';
+    }),
+  ),
+);
+
+const skill = Skill.make({
+  key: 'org.dxos.skill.test',
+  name: 'Test skill',
+  tools: Skill.toolDefinitions({ operations: [ReadName] }),
+});
+
+const TestLayer = Layer.empty.pipe(
+  Layer.provideMerge(ToolExecutionServices),
+  Layer.provideMerge(
+    AssistantTestLayer({
+      aiServicePreset: 'edge-remote',
+      operationHandlers: Handlers,
+      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();
+        yield* new AiRequest.Request({ observer: GenerationObserver.fromPrinter(new ConsolePrinter()) }).run({
+          prompt: `What is the name of the organization? ${org.id}`,
+          toolkit: yield* createToolkit({
+            skills: [skill],
+          }),
+        });
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+    MemoizedAiService.isGenerationEnabled() ? 240_000 : 30_000,
+  );
+});

package/src/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// Re-exports the agent-service barrel: `AgentService` namespace (API from @dxos/compute +
+// createSession/layer), `AGENT_PROCESS_KEY`, and the delegation types.
+export * from './agent-service';

package/src/testing/ResearchService.ts

@@ -0,0 +1,144 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Context from 'effect/Context';
+import * as Deferred from 'effect/Deferred';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Queue from 'effect/Queue';
+
+import { log } from '@dxos/log';
+import { Organization } from '@dxos/types';
+
+//
+// Test data.
+//
+
+export const getTestData = () => ({
+  organizations: [
+    Organization.make({
+      name: 'Cyberdyne Systems',
+      website: 'https://cyberdyne.com',
+    }),
+    Organization.make({
+      name: 'Acme Robotics',
+      website: 'https://acmerobotics.example',
+    }),
+    Organization.make({
+      name: 'Globex Research',
+      website: 'https://globex.example',
+    }),
+  ],
+  research: {
+    'https://cyberdyne.com': `
+      Cyberdyne Systems is a company that builds AI agents.
+      They are based in San Francisco, California.
+      They were founded in 1984.
+      They are a public company.
+      They are listed on the NASDAQ under the symbol CYBR.
+      They are a member of the S&P 500 index.
+    `,
+    'https://acmerobotics.example': `
+      Acme Robotics designs industrial automation and collaborative robots.
+      They are headquartered in Austin, Texas.
+      They were founded in 2010.
+      They serve manufacturing and logistics customers worldwide.
+    `,
+    'https://globex.example': `
+      Globex Research runs applied R&D labs focused on materials science and energy storage.
+      They are based in Cambridge, Massachusetts.
+      They partner with universities and government grants programs.
+      Their flagship product line is solid-state battery prototypes for EVs.
+    `,
+  } as Record<string, string>,
+});
+
+export interface Task {
+  id: string;
+  state: 'pending' | 'completed' | 'interrupted';
+  website: string;
+  deferred: Deferred.Deferred<string>;
+}
+
+export interface Service {
+  getTasks: () => readonly Task[];
+  research: (website: string) => Effect.Effect<string>;
+  waitForTaskToAppear: () => Effect.Effect<void>;
+  completeOneTask: () => Effect.Effect<void>;
+  completeAllTasks: () => Effect.Effect<void>;
+}
+
+export class ResearchService extends Context.Tag('@dxos/functions-runtime/testing/ResearchService')<
+  ResearchService,
+  Service
+>() {}
+
+export const layer = Layer.effect(
+  ResearchService,
+  Effect.gen(function* () {
+    const taskSignal = yield* Queue.unbounded<void>();
+    const tasks: Task[] = [];
+    const complete = (task: Task) =>
+      Effect.gen(function* () {
+        log.info('complete research', { id: task.id, website: task.website });
+        task.state = 'completed';
+        const result = getTestData().research[task.website];
+        if (!result) {
+          yield* Effect.die(new Error(`No research found for ${task.website}`));
+          return;
+        }
+        yield* Deferred.succeed(task.deferred, result);
+      });
+
+    return ResearchService.of({
+      getTasks: () => tasks,
+      research: (website: string) =>
+        Effect.gen(function* () {
+          const id = crypto.randomUUID();
+          const task: Task = { id, state: 'pending', website, deferred: yield* Deferred.make<string>() };
+          log.info('start research', { id, website });
+          tasks.push(task);
+          yield* Queue.offer(taskSignal, undefined);
+          return yield* Deferred.await(task.deferred).pipe(
+            Effect.onInterrupt(() =>
+              Effect.sync(() => {
+                log.info('interrupt research', { id, website: task.website });
+                task.state = 'interrupted';
+              }),
+            ),
+          );
+        }),
+      waitForTaskToAppear: () =>
+        Effect.gen(function* () {
+          while (true) {
+            const task = tasks.find((t) => t.state === 'pending');
+            if (task) {
+              return;
+            }
+            yield* Queue.take(taskSignal);
+          }
+        }),
+      completeOneTask: () =>
+        Effect.gen(function* () {
+          const task = tasks.find((t) => t.state === 'pending');
+          if (!task) {
+            return;
+          }
+          yield* complete(task);
+        }),
+      completeAllTasks: () =>
+        Effect.gen(function* () {
+          while (true) {
+            const task = tasks.find((t) => t.state === 'pending');
+            if (!task) {
+              return;
+            }
+            yield* complete(task);
+          }
+        }),
+    });
+  }),
+);

package/src/testing/assistant-test-layer.ts

@@ -0,0 +1,299 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Registry as AtomRegistry } from '@effect-atom/atom';
+import * as LanguageModel from '@effect/ai/LanguageModel';
+import * as KeyValueStore from '@effect/platform/KeyValueStore';
+import * as Array from 'effect/Array';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Match from 'effect/Match';
+
+import { AiService, OpaqueToolkit, Provider } from '@dxos/ai';
+import { TestAiService } from '@dxos/ai/testing';
+import { Harness } from '@dxos/assistant';
+import {
+  AgentService,
+  Credential,
+  Instructions,
+  Operation,
+  OperationHandlerSet,
+  Process,
+  ServiceNotAvailableError,
+  ServiceResolver,
+  Skill,
+  Trace,
+  Trigger,
+} from '@dxos/compute';
+import {
+  FeedTraceSink,
+  ProcessManager,
+  ProcessMonitor,
+  RemoteProcessManager,
+  TriggerDispatcher,
+  TriggerStateStore,
+  configuredCredentialsLayer,
+} from '@dxos/compute-runtime';
+import { TestDatabaseLayer } from '@dxos/compute-runtime/testing';
+import { Database, Feed, Registry, Tag, Type } from '@dxos/echo';
+import { registryLayer } from '@dxos/echo-client';
+import { type TestContextService } from '@dxos/effect/testing';
+import { DXN } from '@dxos/keys';
+
+import { AgentService as AgentServiceRuntime } from '../agent-service';
+import { traceSinkPrettyLayer } from './trace-pretty-print';
+
+interface TestLayerOptions {
+  aiServicePreset?: 'direct' | 'edge-local' | 'edge-remote' | 'ollama';
+
+  /**
+   * Overrides the AI service entirely (e.g. a scripted model for deterministic e2e tests).
+   * When set, `aiServicePreset` and `disableLlmMemoization` are ignored.
+   */
+  aiService?: Layer.Layer<AiService.AiService>;
+  model?: DXN.DXN;
+  /** Provider the model resolves through; defaults to `ollama` for the ollama preset, else `edge`. */
+  provider?: DXN.DXN;
+  operationHandlers?: OperationHandlerSet.OperationHandlerSet | OperationHandlerSet.OperationHandlerSet[];
+  toolkits?: OpaqueToolkit.OpaqueToolkit[];
+  types?: Type.AnyEntity[];
+  skills?: Skill.Skill[];
+  credentials?: Credential.ServiceCredential[];
+
+  /**
+   * Tracing configuration.
+   * - `'feed'` persists trace events to a FeedTraceSink (queryable from the database).
+   * @default 'noop'
+   */
+  tracing?: 'noop' | 'console' | 'pretty' | 'feed';
+
+  disableLlmMemoization?: boolean;
+
+  /**
+   * Patterns matching run-specific values (e.g. timestamps derived from TestClock) that should be
+   * canonicalized for memoized-conversation matching. Forwarded to `TestAiService`. Opt-in.
+   */
+  dynamicValuePatterns?: readonly RegExp[];
+
+  /**
+   * Options for the agent process (system prompt, tool backgrounding, delegation strategy, etc.).
+   * The model defaults to the resolved test-layer model when not set here.
+   */
+  agent?: AgentServiceRuntime.AgentServiceOptions;
+
+  /**
+   * Extra services to make available in the service resolver.
+   * Operations can depend on those services.
+   */
+  extraServices?: Layer.Layer<never, never, never>;
+}
+
+export type AssistantTestServices =
+  | LanguageModel.LanguageModel
+  | Credential.CredentialsService
+  | AgentService.AgentService
+  | AiService.AiService
+  | Database.Service
+  | Registry.Service
+  | OpaqueToolkit.OpaqueToolkitProvider
+  | Operation.Service
+  | ProcessManager.Service
+  | Process.ProcessMonitorService
+  | AtomRegistry.AtomRegistry
+  | OperationHandlerSet.OperationHandlerProvider
+  | KeyValueStore.KeyValueStore
+  | ServiceResolver.ServiceResolver
+  | Trace.TraceService
+  | Trace.TraceSink
+  | FeedTraceSink.FeedTraceSink;
+
+export const AssistantTestLayer = (
+  options: TestLayerOptions = {},
+): Layer.Layer<AssistantTestServices, never, TestContextService> => {
+  const resolvedModel: DXN.DXN =
+    options.model ??
+    (options.aiServicePreset === 'ollama'
+      ? DXN.make('com.openai.model.gpt-oss-20b.default')
+      : DXN.make('com.anthropic.model.claude-opus-4-8.default'));
+
+  // The catalog's shared model ids need a provider to resolve; pair the resolved model with the
+  // provider its preset registers a resolver for.
+  const resolvedProvider: DXN.DXN =
+    options.provider ?? (options.aiServicePreset === 'ollama' ? Provider.ollama.id : Provider.edge.id);
+
+  const agentOptions: AgentServiceRuntime.AgentServiceOptions = { ...options.agent };
+  agentOptions.model ??= resolvedModel;
+  agentOptions.provider ??= resolvedProvider;
+
+  // The resolver materialises `HarnessService` (Tier B needs `ProcessManager.Service`), but
+  // `ProcessManager.layer` requires the `ServiceResolver` — a construction cycle. Resolve it by
+  // sharing a late-bound holder: the resolver reads the manager lazily (only at resolution time,
+  // when the manager exists), and a downstream layer fills the holder once it is built.
+  const processManagerHolder: ProcessManagerHolder = {};
+
+  return Layer.empty.pipe(
+    Layer.provideMerge(ProcessManager.ProcessOperationInvoker.layer),
+    Layer.provideMerge(ProcessMonitor.layer),
+    Layer.provideMerge(RemoteProcessManager.layerNoop),
+    Layer.provideMerge(AgentServiceRuntime.layer(agentOptions)),
+    Layer.provideMerge(Trace.testTraceService({ meta: { processName: 'test' } })),
+    // Order matters: in a `provideMerge` chain each layer's *requirements* are satisfied only by
+    // layers added later (whose outputs feed it). `captureProcessManager` needs the manager, the
+    // manager needs the `ServiceResolver`, and the resolver needs nothing (it reads the manager via
+    // the holder), so they must appear in exactly this order.
+    Layer.provideMerge(captureProcessManager(processManagerHolder)),
+    Layer.provideMerge(ProcessManager.layer({ idGenerator: ProcessManager.SequentialIdGenerator })),
+    Layer.provideMerge(AssistantTestServiceResolverLayer(options, processManagerHolder)),
+    Layer.provideMerge(AiService.model(DXN.getName(resolvedModel), { provider: resolvedProvider })),
+    Layer.provideMerge(AssistantTestTracingLayer(options.tracing ?? 'noop')),
+    Layer.provideMerge(
+      options.aiService ??
+        TestAiService({
+          preset: options.aiServicePreset,
+          disableMemoization: options.disableLlmMemoization,
+          dynamicValuePatterns: options.dynamicValuePatterns,
+        }),
+    ),
+    Layer.provideMerge(AssistantTestBaseLayer(options)),
+    Layer.orDie,
+  );
+};
+
+/** Late-bound reference to the {@link ProcessManager.Service}, filled once the manager is built. */
+interface ProcessManagerHolder {
+  current?: Context.Tag.Service<ProcessManager.Service>;
+}
+
+/** Fills the {@link ProcessManagerHolder} once the manager is available, breaking the build cycle. */
+const captureProcessManager = (holder: ProcessManagerHolder): Layer.Layer<never, never, ProcessManager.Service> =>
+  Layer.effectDiscard(
+    Effect.gen(function* () {
+      holder.current = yield* ProcessManager.Service;
+    }),
+  );
+
+/**
+ * Service resolver for testing.
+ */
+export const AssistantTestServiceResolverLayer = (
+  { extraServices = Layer.empty }: Pick<TestLayerOptions, 'extraServices'>,
+  processManagerHolder: ProcessManagerHolder,
+) =>
+  Layer.scoped(
+    ServiceResolver.ServiceResolver,
+    Effect.gen(function* () {
+      const services = yield* Effect.context<Database.Service>().pipe(
+        Effect.map(Context.pick(Database.Service)),
+        Effect.map(Layer.succeedContext),
+      );
+
+      const extraServicesRt = yield* Layer.toRuntime(extraServices);
+
+      return ServiceResolver.compose(
+        ServiceResolver.succeed(Harness.HarnessService, (context) =>
+          Effect.gen(function* () {
+            if (!context.conversation) {
+              return yield* Effect.fail(new ServiceNotAvailableError(Harness.HarnessService.key));
+            }
+            // Read the manager lazily: the resolver is invoked at spawn time, by which point the
+            // holder has been filled (see the construction-cycle note in `AssistantTestLayer`).
+            const processManager = processManagerHolder.current;
+            if (!processManager) {
+              return yield* Effect.fail(new ServiceNotAvailableError(ProcessManager.Service.key));
+            }
+            const runtime = yield* Effect.runtime<Database.Service>();
+            return yield* Harness.make({ conversation: context.conversation, processManager, runtime });
+          }).pipe(Effect.provide(services)),
+        ),
+        yield* ServiceResolver.fromRequirements(
+          Database.Service,
+          OpaqueToolkit.OpaqueToolkitProvider,
+          AiService.AiService,
+          Registry.Service,
+          Credential.CredentialsService,
+        ),
+        ServiceResolver.fromContext(extraServicesRt.context),
+      );
+    }),
+  );
+
+/**
+ * Only storage + registry.
+ */
+export const AssistantTestBaseLayer = ({
+  operationHandlers = [],
+  toolkits = [],
+  types = [],
+  credentials = [],
+  skills = [],
+}: Pick<TestLayerOptions, 'operationHandlers' | 'toolkits' | 'types' | 'skills' | 'tracing' | 'credentials'>) => {
+  const toolkit = OpaqueToolkit.merge(...toolkits);
+  const operationHandlersSet = Array.isArray(operationHandlers)
+    ? OperationHandlerSet.merge(...operationHandlers)
+    : operationHandlers;
+  types.push(
+    Skill.Skill,
+    Instructions.Instructions,
+    Operation.PersistentOperation,
+    Feed.Feed,
+    Trigger.Trigger,
+    Tag.Tag,
+  );
+  types = Array.dedupeWith(types, (a, b) => Type.getTypename(a) === Type.getTypename(b));
+
+  return Layer.empty.pipe(
+    Layer.provideMerge(
+      TestDatabaseLayer({
+        spaceKey: 'fixed',
+        types,
+      }),
+    ),
+    Layer.provideMerge(configuredCredentialsLayer(credentials)),
+    Layer.provideMerge(
+      Layer.effect(
+        Registry.Service,
+        Effect.gen(function* () {
+          const handlerSet = yield* OperationHandlerSet.OperationHandlerProvider;
+          const registry = yield* Registry.Service;
+          const handlers = yield* handlerSet.handlers;
+          registry.add(handlers.map(Operation.serialize));
+          return registry;
+        }),
+      ),
+    ),
+    Layer.provideMerge(registryLayer({ initial: skills })),
+    Layer.provideMerge(OpaqueToolkit.providerLayer(toolkit)),
+    Layer.provideMerge(OperationHandlerSet.provide(operationHandlersSet)),
+    Layer.provideMerge(KeyValueStore.layerMemory),
+    Layer.provideMerge(AtomRegistry.layer),
+    Layer.orDie,
+  );
+};
+
+const AssistantTestTracingLayer = (
+  mode: 'noop' | 'console' | 'pretty' | 'feed',
+): Layer.Layer<FeedTraceSink.FeedTraceSink | Trace.TraceSink, never, Database.Service> =>
+  Match.value(mode).pipe(
+    Match.when('noop', () => Layer.mergeAll(Trace.layerNoop, FeedTraceSink.layerNoop)),
+    Match.when('console', () => Layer.mergeAll(Trace.layerConsole, FeedTraceSink.layerNoop)),
+    Match.when('pretty', () => Layer.mergeAll(traceSinkPrettyLayer(), FeedTraceSink.layerNoop)),
+    Match.when('feed', () => FeedTraceSink.layerLiveWithDirectSink),
+    Match.exhaustive,
+  );
+
+interface TestLayerWithTriggersOptions extends TestLayerOptions {}
+
+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.provide(AtomRegistry.layer),
+    ),
+    TriggerStateStore.layerMemory,
+  ) as any;

package/src/testing/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './assistant-test-layer';
+export * from './trace-pretty-print';
+export * as ResearchService from './ResearchService';

package/src/testing/trace-pretty-print.ts

@@ -0,0 +1,55 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { ConsolePrinter } from '@dxos/ai';
+import { CompleteBlock } from '@dxos/assistant';
+import { Process, Trace } from '@dxos/compute';
+import { FeedTraceSink } from '@dxos/compute-runtime';
+import { Database, Filter, Query } from '@dxos/echo';
+
+/**
+ * Pretty-prints assistant trace messages to stdout (CompleteBlock, process spawn/exit).
+ */
+export const prettyPrintTraceMessage = (message: Trace.Message): void => {
+  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}`);
+    }
+  }
+};
+
+/** {@link Trace.TraceSink} layer that mirrors {@link AssistantTestLayer}'s `tracing: 'pretty'` mode. */
+export const traceSinkPrettyLayer = (): Layer.Layer<Trace.TraceSink> =>
+  Layer.succeed(Trace.TraceSink, {
+    write: prettyPrintTraceMessage,
+  });
+
+/**
+ * Subscribes to the space trace feed and pretty-prints newly appended messages.
+ * Returns an unsubscribe function. Requires ambient {@link Database.Service}.
+ */
+export const traceFeedPrettyPrintSubscription = Effect.gen(function* () {
+  const feed = yield* FeedTraceSink.getOrCreateTraceFeed();
+  const queryResult = yield* Database.query(Query.select(Filter.type(Trace.Message)).from(feed));
+  const seen = new Set(queryResult.runSync().map((message) => message.id));
+
+  return queryResult.subscribe((result) => {
+    for (const message of result.results) {
+      if (seen.has(message.id)) {
+        continue;
+      }
+      seen.add(message.id);
+      prettyPrintTraceMessage(message);
+    }
+  });
+});