@dxos/functions 0.8.4-main.f9ba587 → 0.8.4-main.fd6878d

package/src/services/local-function-execution.ts

@@ -0,0 +1,74 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Context, Effect, Layer, Schema } from 'effect';
+
+import { todo } from '@dxos/debug';
+
+import { FunctionError } from '../errors';
+import type { FunctionContext, FunctionDefinition } from '../handler';
+
+import type { Services } from './service-container';
+
+export class LocalFunctionExecutionService extends Context.Tag('@dxos/functions/LocalFunctionExecutionService')<
+  LocalFunctionExecutionService,
+  {
+    // TODO(dmaretskyi): This should take function id instead of the definition object.
+    // TODO(dmaretskyi): Services should be satisfied from environment rather then bubbled up.
+    invokeFunction(fnDef: FunctionDefinition<any, any>, input: unknown): Effect.Effect<unknown, never, Services>;
+  }
+>() {
+  static layer = Layer.succeed(LocalFunctionExecutionService, {
+    invokeFunction: (fnDef, input) => invokeFunction(fnDef, input),
+  });
+
+  static invokeFunction: <F extends FunctionDefinition.Any>(
+    fnDef: F,
+    input: FunctionDefinition.Input<F>,
+  ) => Effect.Effect<FunctionDefinition.Output<F>, never, Services | LocalFunctionExecutionService> =
+    Effect.serviceFunctionEffect(LocalFunctionExecutionService, (_) => _.invokeFunction as any);
+}
+
+const invokeFunction = (fnDef: FunctionDefinition<any, any>, input: any): Effect.Effect<unknown, never, Services> =>
+  Effect.gen(function* () {
+    // Assert input matches schema
+    const assertInput = fnDef.inputSchema.pipe(Schema.asserts);
+    (assertInput as any)(input);
+
+    const context: FunctionContext = {
+      space: undefined,
+      getService: () => todo(),
+      getSpace: async (_spaceId: any) => {
+        throw new Error('Not available. Use the database service instead.');
+      },
+    };
+
+    // TODO(dmaretskyi): This should be delegated to a function invoker service.
+    const data = yield* Effect.gen(function* () {
+      const result = fnDef.handler({ context, data: input });
+      if (Effect.isEffect(result)) {
+        return yield* (result as Effect.Effect<unknown, unknown, Services>).pipe(Effect.orDie);
+      } else if (
+        typeof result === 'object' &&
+        result !== null &&
+        'then' in result &&
+        typeof result.then === 'function'
+      ) {
+        return yield* Effect.promise(() => result);
+      } else {
+        return result;
+      }
+    }).pipe(
+      Effect.orDie,
+      Effect.catchAllDefect((defect) =>
+        Effect.die(new FunctionError('Error running function', { context: { name: fnDef.name }, cause: defect })),
+      ),
+    );
+
+    // Assert output matches schema
+    const assertOutput = fnDef.outputSchema?.pipe(Schema.asserts);
+    (assertOutput as any)(data);
+
+    return data;
+  }).pipe(Effect.withSpan('invokeFunction', { attributes: { name: fnDef.name } }));

package/src/services/queues.ts

@@ -2,11 +2,16 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Context, Layer } from 'effect';
+import { Context, Effect, Layer } from 'effect';
 
+import type { Obj, Relation } from '@dxos/echo';
 import type { Queue, QueueAPI, QueueFactory } from '@dxos/echo-db';
+import type { DXN, QueueSubspaceTag } from '@dxos/keys';
 
-export class QueueService extends Context.Tag('QueueService')<
+/**
+ * Gives access to all queues.
+ */
+export class QueueService extends Context.Tag('@dxos/functions/QueueService')<
   QueueService,
   {
     /**
@@ -16,27 +21,57 @@ export class QueueService extends Context.Tag('QueueService')<
 
     /**
      * The queue that is used to store the context of the current research.
+     * @deprecated Use `ContextQueueService` instead.
      */
-    // TODO(dmaretskyi): Is this really part of the queue service?
-    readonly contextQueue: Queue | undefined;
+    readonly queue: Queue | undefined;
   }
 >() {
   static notAvailable = Layer.succeed(QueueService, {
     queues: {
-      get(dxn) {
+      get(_dxn) {
         throw new Error('Queues not available');
       },
       create() {
         throw new Error('Queues not available');
       },
     },
-    contextQueue: undefined,
+    queue: undefined,
   });
 
-  static make = (queues: QueueFactory, contextQueue: Queue | undefined): Context.Tag.Service<QueueService> => {
+  static make = (queues: QueueFactory, queue?: Queue): Context.Tag.Service<QueueService> => {
     return {
       queues,
-      contextQueue,
+      queue,
     };
   };
+
+  static layer = (queues: QueueFactory, queue?: Queue): Layer.Layer<QueueService> =>
+    Layer.succeed(QueueService, QueueService.make(queues, queue));
+
+  /**
+   * Gets a queue by its DXN.
+   */
+  static getQueue = <T extends Obj.Any | Relation.Any = Obj.Any | Relation.Any>(
+    dxn: DXN,
+  ): Effect.Effect<Queue<T>, never, QueueService> => QueueService.pipe(Effect.map(({ queues }) => queues.get<T>(dxn)));
+
+  /**
+   * Creates a new queue.
+   */
+  static createQueue = <T extends Obj.Any | Relation.Any = Obj.Any | Relation.Any>(options?: {
+    subspaceTag?: QueueSubspaceTag;
+  }): Effect.Effect<Queue<T>, never, QueueService> =>
+    QueueService.pipe(Effect.map(({ queues }) => queues.create<T>(options)));
+}
+
+/**
+ * Gives access to a specific queue passed as a context.
+ */
+export class ContextQueueService extends Context.Tag('@dxos/functions/ContextQueueService')<
+  ContextQueueService,
+  {
+    readonly queue: Queue;
+  }
+>() {
+  static layer = (queue: Queue) => Layer.succeed(ContextQueueService, { queue });
 }

package/src/services/{function-call-service.ts → remote-function-execution-service.ts}

@@ -2,20 +2,20 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Context } from 'effect';
+import { Context, Layer } from 'effect';
 
 import type { SpaceId } from '@dxos/keys';
 
 /**
  * Allows calling into other functions.
  */
-export class FunctionCallService extends Context.Tag('FunctionCallService')<
-  FunctionCallService,
+export class RemoteFunctionExecutionService extends Context.Tag('@dxos/functions/RemoteFunctionExecutionService')<
+  RemoteFunctionExecutionService,
   {
     callFunction(deployedFunctionId: string, input: any, spaceId?: SpaceId): Promise<any>;
   }
 >() {
-  static fromClient(baseUrl: string, spaceId: SpaceId): Context.Tag.Service<FunctionCallService> {
+  static fromClient(baseUrl: string, spaceId: SpaceId): Context.Tag.Service<RemoteFunctionExecutionService> {
     return {
       callFunction: async (deployedFunctionId: string, input: any) => {
         const url = getInvocationUrl(deployedFunctionId, baseUrl, { spaceId });
@@ -32,13 +32,15 @@ export class FunctionCallService extends Context.Tag('FunctionCallService')<
     };
   }
 
-  static mock = () => {
+  static mock = (): Context.Tag.Service<RemoteFunctionExecutionService> => {
     return {
       callFunction: async (deployedFunctionId: string, input: any) => {
         return input;
       },
     };
   };
+
+  static mockLayer = Layer.succeed(RemoteFunctionExecutionService, RemoteFunctionExecutionService.mock());
 }
 
 // TODO(dmaretskyi): Reconcile with `getInvocationUrl` in `@dxos/functions/edge`.

package/src/services/service-container.ts

@@ -2,68 +2,65 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Layer, type Context } from 'effect';
+import { type Context, Layer } from 'effect';
+
+import { AiService } from '@dxos/ai';
+import { entries } from '@dxos/util';
 
-import { AiService } from './ai';
 import { ConfiguredCredentialsService, CredentialsService } from './credentials';
 import { DatabaseService } from './database';
-import { EventLogger } from './event-logger';
-import { FunctionCallService } from './function-call-service';
+import { ComputeEventLogger } from './event-logger';
 import { QueueService } from './queues';
-import { ToolResolverService } from './tool-resolver';
+import { RemoteFunctionExecutionService } from './remote-function-execution-service';
 import { TracingService } from './tracing';
 
+// TODO(dmaretskyi): Refactor this module to only rely on tags and not the human-assigned names.
+
 /**
- * List of all service tags and their names.
+ * List of all services.
  */
-export interface ServiceTagRecord {
-  ai: AiService;
-  credentials: CredentialsService;
-  database: DatabaseService;
-  eventLogger: EventLogger;
-  functionCallService: FunctionCallService;
-  tracing: TracingService;
-  queues: QueueService;
-  toolResolver: ToolResolverService;
-}
+const SERVICES = {
+  ai: AiService.AiService,
+  credentials: CredentialsService,
+  database: DatabaseService,
+  eventLogger: ComputeEventLogger,
+  functionCallService: RemoteFunctionExecutionService,
+  queues: QueueService,
+  tracing: TracingService,
+} as const satisfies Record<string, Context.TagClass<any, string, any>>;
+
+/**
+ * Mapping of service names to their tags.
+ */
+export type ServiceTagRecord = {
+  [K in keyof typeof SERVICES]: (typeof SERVICES)[K] extends { new (_: never): infer T } ? T : never;
+};
 
 /**
- * List of all services and their runtime types.
+ * Mapping of service names to their runtime types.
  */
 export type ServiceRecord = {
   [K in keyof ServiceTagRecord]: Context.Tag.Service<ServiceTagRecord[K]>;
 };
 
 /**
- * Union of all services.
+ * Union of all services tags.
  */
 export type Services = ServiceTagRecord[keyof ServiceTagRecord];
 
-const SERVICE_MAPPING: Record<string, keyof ServiceRecord> = {
-  [AiService.key]: 'ai',
-  [CredentialsService.key]: 'credentials',
-  [DatabaseService.key]: 'database',
-  [EventLogger.key]: 'eventLogger',
-  [FunctionCallService.key]: 'functionCallService',
-  [QueueService.key]: 'queues',
-  [TracingService.key]: 'tracing',
-  [ToolResolverService.key]: 'toolResolver',
-};
+const SERVICE_MAPPING: Record<string, keyof ServiceRecord> = Object.fromEntries(
+  entries(SERVICES).map(([name, tag]) => [tag.key, name]),
+);
 
-export const SERVICE_TAGS: Context.Tag<any, any>[] = [
-  AiService,
-  CredentialsService,
-  DatabaseService,
-  EventLogger,
-  FunctionCallService,
-  TracingService,
-  QueueService,
-];
+export const SERVICE_TAGS: Context.Tag<any, any>[] = Object.values(SERVICES);
 
 const DEFAULT_SERVICES: Partial<ServiceRecord> = {
   tracing: TracingService.noop,
 };
 
+/**
+ * @deprecated
+ */
 export class ServiceContainer {
   private _services: Partial<ServiceRecord> = { ...DEFAULT_SERVICES };
 
@@ -91,10 +88,14 @@ export class ServiceContainer {
     return new ServiceContainer().setServices({ ...this._services });
   }
 
-  // TODO(dmaretskyi): `getService` is designed to error at runtime if the service is not available, but layer forces us to provide all services and makes stubs for the ones that are not available.
+  // TODO(dmaretskyi): `getService` is designed to error at runtime if the service is not available, but Layer forces us to provide all services and makes stubs for the ones that are not available.
   createLayer(): Layer.Layer<Services> {
-    const ai = this._services.ai != null ? Layer.succeed(AiService, this._services.ai) : AiService.notAvailable;
-    const credentials = Layer.succeed(CredentialsService, new ConfiguredCredentialsService());
+    const ai =
+      this._services.ai != null ? Layer.succeed(AiService.AiService, this._services.ai) : AiService.notAvailable;
+    const credentials = Layer.succeed(
+      CredentialsService,
+      this._services.credentials ?? new ConfiguredCredentialsService(),
+    );
     const database =
       this._services.database != null
         ? Layer.succeed(DatabaseService, this._services.database)
@@ -102,26 +103,12 @@ export class ServiceContainer {
     const queues =
       this._services.queues != null ? Layer.succeed(QueueService, this._services.queues) : QueueService.notAvailable;
     const tracing = Layer.succeed(TracingService, this._services.tracing ?? TracingService.noop);
-    const eventLogger = Layer.succeed(EventLogger, this._services.eventLogger ?? EventLogger.noop);
+    const eventLogger = Layer.succeed(ComputeEventLogger, this._services.eventLogger ?? ComputeEventLogger.noop);
     const functionCallService = Layer.succeed(
-      FunctionCallService,
-      this._services.functionCallService ?? FunctionCallService.mock(),
-    );
-    const toolResolver = Layer.succeed(
-      ToolResolverService,
-      this._services.toolResolver ?? ToolResolverService.notAvailable,
+      RemoteFunctionExecutionService,
+      this._services.functionCallService ?? RemoteFunctionExecutionService.mock(),
     );
 
-    return Layer.mergeAll(
-      //
-      ai,
-      credentials,
-      database,
-      queues,
-      tracing,
-      eventLogger,
-      functionCallService,
-      toolResolver,
-    );
+    return Layer.mergeAll(ai, credentials, database, queues, tracing, eventLogger, functionCallService);
   }
 }

package/src/services/service-registry.test.ts

@@ -0,0 +1,42 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, it } from '@effect/vitest';
+import { Context, Effect, Layer, Option } from 'effect';
+
+import { ServiceRegistry } from './service-registry';
+
+class MyTag extends Context.Tag('MyTag')<MyTag, { value: string }>() {}
+
+const mockRegistry = Layer.succeed(ServiceRegistry, {
+  resolve: (tag) => ((tag as any) === MyTag ? Option.some({ value: 'test' } as any) : Option.none()),
+});
+
+describe('ServiceRegistry', () => {
+  it.effect(
+    'provide',
+    Effect.fn(function* ({ expect }) {
+      const body = Effect.gen(function* () {
+        const { value } = yield* MyTag;
+        expect(value).toEqual('test');
+      });
+
+      const eff = body.pipe(ServiceRegistry.provide(MyTag));
+      yield* eff;
+    }, Effect.provide(mockRegistry)),
+  );
+
+  it.effect(
+    'provide or die',
+    Effect.fn(function* ({ expect }) {
+      const body = Effect.gen(function* () {
+        const { value } = yield* MyTag;
+        expect(value).toEqual('test');
+      });
+
+      const eff = body.pipe(ServiceRegistry.provideOrDie(MyTag));
+      yield* eff;
+    }, Effect.provide(mockRegistry)),
+  );
+});

package/src/services/service-registry.ts

@@ -0,0 +1,59 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Context, Effect, type Option, flow } from 'effect';
+
+import { ServiceNotAvailableError } from '../errors';
+
+export namespace ServiceRegistry {
+  export interface Service {
+    resolve: <T extends Context.Tag<any, any>>(tag: T) => Option.Option<Context.Tag.Service<T>>;
+  }
+}
+
+export class ServiceRegistry extends Context.Tag('@dxos/functions/ServiceRegistry')<
+  ServiceRegistry,
+  ServiceRegistry.Service
+>() {
+  /**
+   * Resolves the service from the registry.
+   * @param tag Service tag to resolve.
+   * @throws {@link ServiceNotAvailableError} if the service is not found.
+   * @returns Effect that resolve to the service.
+   */
+  static resolve: <T extends Context.Tag<any, any>>(
+    tag: T,
+  ) => Effect.Effect<T, ServiceNotAvailableError, ServiceRegistry> = (tag) =>
+    ServiceRegistry.pipe(
+      Effect.flatMap((_) => _.resolve(tag)),
+      Effect.mapError(() => new ServiceNotAvailableError(tag.key)),
+    );
+
+  static provide: {
+    <Tags extends [Context.Tag<any, any>, ...Context.Tag<any, any>[]]>(
+      ...tags: Tags
+    ): <A, E, R>(
+      effect: Effect.Effect<A, E, R>,
+    ) => Effect.Effect<
+      A,
+      E | ServiceNotAvailableError,
+      Exclude<R, { [K in keyof Tags]: Context.Tag.Identifier<Tags[K]> }[number]> | ServiceRegistry
+    >;
+  } = (...tags) => (flow as any)(...tags.map((tag) => Effect.provideServiceEffect(tag, ServiceRegistry.resolve(tag))));
+
+  static provideOrDie: {
+    <Tags extends [Context.Tag<any, any>, ...Context.Tag<any, any>[]]>(
+      ...tags: Tags
+    ): <A, E, R>(
+      effect: Effect.Effect<A, E, R>,
+    ) => Effect.Effect<
+      A,
+      E,
+      Exclude<R, { [K in keyof Tags]: Context.Tag.Identifier<Tags[K]> }[number]> | ServiceRegistry
+    >;
+  } = (...tags) =>
+    (flow as any)(
+      ...tags.map((tag) => Effect.provideServiceEffect(tag, ServiceRegistry.resolve(tag).pipe(Effect.orDie))),
+    );
+}

package/src/services/tracing.ts

@@ -2,11 +2,17 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Context } from 'effect';
+import { Context, Effect, Layer } from 'effect';
 
+import { AgentStatus } from '@dxos/ai';
+import { Obj } from '@dxos/echo';
 import type { AnyEchoObject } from '@dxos/echo-schema';
 
-export class TracingService extends Context.Tag('TracingService')<
+/**
+ * Provides a way for compute primitives (functions, workflows, tools)
+ * to emit an execution trace as a series of structured ECHO objects.
+ */
+export class TracingService extends Context.Tag('@dxos/functions/TracingService')<
   TracingService,
   {
     /**
@@ -18,10 +24,21 @@ export class TracingService extends Context.Tag('TracingService')<
 >() {
   static noop: Context.Tag.Service<TracingService> = { write: () => {} };
 
+  static layerNoop = Layer.succeed(TracingService, TracingService.noop);
+
   static console: Context.Tag.Service<TracingService> = {
     write: (event) => {
       // eslint-disable-next-line no-console
       console.log(event);
     },
   };
+
+  /**
+   * Emit the current human-readable execution status.
+   */
+  static emitStatus: (data: Obj.MakeProps<typeof AgentStatus>) => Effect.Effect<void, never, TracingService> =
+    Effect.fnUntraced(function* (data) {
+      const tracing = yield* TracingService;
+      tracing.write(Obj.make(AgentStatus, data));
+    });
 }

package/src/testing/index.ts

@@ -3,3 +3,4 @@
 //
 
 export * from './services';
+export * from './layer';

package/src/testing/layer.ts

@@ -0,0 +1,31 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Context, Effect, Layer } from 'effect';
+import type { Schema } from 'effect';
+
+import { EchoTestBuilder } from '@dxos/echo-db/testing';
+import type { EchoHostIndexingConfig } from '@dxos/echo-pipeline';
+import { accuireReleaseResource } from '@dxos/effect';
+
+import { DatabaseService, QueueService } from '../services';
+
+const testBuilder = accuireReleaseResource(() => new EchoTestBuilder());
+
+export type TestDatabaseOptions = {
+  indexing?: Partial<EchoHostIndexingConfig>;
+  types?: Schema.Schema.AnyNoContext[];
+};
+
+export const TestDatabaseLayer = ({ indexing, types }: TestDatabaseOptions = {}) =>
+  Layer.scopedContext(
+    Effect.gen(function* () {
+      const builder = yield* testBuilder;
+      const { db, queues } = yield* Effect.promise(() => builder.createDatabase({ indexing, types }));
+      return Context.mergeAll(
+        Context.make(DatabaseService, DatabaseService.make(db)),
+        Context.make(QueueService, QueueService.make(queues, undefined)),
+      );
+    }),
+  );

package/src/testing/logger.ts

@@ -2,15 +2,15 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Effect, type Context } from 'effect';
+import { type Context, Effect } from 'effect';
 
 import { LogLevel } from '@dxos/log';
 
-import { type EventLogger, createEventLogger } from '../services';
+import { type ComputeEventLogger, createEventLogger } from '../services';
 
-export const noopLogger: Context.Tag.Service<EventLogger> = {
+export const noopLogger: Context.Tag.Service<ComputeEventLogger> = {
   log: () => Effect.succeed(undefined),
   nodeId: undefined,
 };
 
-export const consoleLogger: Context.Tag.Service<EventLogger> = createEventLogger(LogLevel.INFO);
+export const consoleLogger: Context.Tag.Service<ComputeEventLogger> = createEventLogger(LogLevel.INFO);