@dxos/functions 0.8.3 → 0.8.4-main.28f8d3d

package/src/services/event-logger.ts

@@ -2,53 +2,81 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Effect, Context } from 'effect';
+import { Context, Effect, Layer, Schema } from 'effect';
 
+import { Obj, Type } from '@dxos/echo';
 import { invariant } from '@dxos/invariant';
-import { log, LogLevel } from '@dxos/log';
+import { LogLevel, log } from '@dxos/log';
 
-export type ComputeEvent =
-  | {
-      type: 'begin-compute';
-      nodeId: string;
-      inputs: Record<string, any>;
-    }
-  | {
-      type: 'end-compute';
-      nodeId: string;
-      outputs: Record<string, any>;
-    }
-  | {
-      type: 'compute-input';
-      nodeId: string;
-      property: string;
-      value: any;
-    }
-  | {
-      type: 'compute-output';
-      nodeId: string;
-      property: string;
-      value: any;
-    }
-  | {
-      type: 'custom';
-      nodeId: string;
-      event: any;
-    };
+import { TracingService } from './tracing';
+
+export const ComputeEventPayload = Schema.Union(
+  Schema.Struct({
+    type: Schema.Literal('begin-compute'),
+    nodeId: Schema.String,
+    inputs: Schema.Record({ key: Schema.String, value: Schema.Any }),
+  }),
+  Schema.Struct({
+    type: Schema.Literal('end-compute'),
+    nodeId: Schema.String,
+    outputs: Schema.Record({ key: Schema.String, value: Schema.Any }),
+  }),
+  Schema.Struct({
+    type: Schema.Literal('compute-input'),
+    nodeId: Schema.String,
+    property: Schema.String,
+    value: Schema.Any,
+  }),
+  Schema.Struct({
+    type: Schema.Literal('compute-output'),
+    nodeId: Schema.String,
+    property: Schema.String,
+    value: Schema.Any,
+  }),
+  Schema.Struct({
+    type: Schema.Literal('custom'),
+    nodeId: Schema.String,
+    event: Schema.Any,
+  }),
+);
+export type ComputeEventPayload = Schema.Schema.Type<typeof ComputeEventPayload>;
 
-export class EventLogger extends Context.Tag('EventLogger')<
-  EventLogger,
-  { readonly log: (event: ComputeEvent) => void; readonly nodeId: string | undefined }
+export const ComputeEvent = Schema.Struct({
+  payload: ComputeEventPayload,
+}).pipe(Type.Obj({ typename: 'dxos.org/type/ComputeEvent', version: '0.1.0' }));
+
+/**
+ * Logs event for the compute workflows.
+ */
+export class ComputeEventLogger extends Context.Tag('@dxos/functions/ComputeEventLogger')<
+  ComputeEventLogger,
+  { readonly log: (event: ComputeEventPayload) => void; readonly nodeId: string | undefined }
 >() {
-  static noop: Context.Tag.Service<EventLogger> = {
+  static noop: Context.Tag.Service<ComputeEventLogger> = {
     log: () => {},
     nodeId: undefined,
   };
+
+  /**
+   * Implements ComputeEventLogger using TracingService.
+   */
+  static layerFromTracing = Layer.effect(
+    ComputeEventLogger,
+    Effect.gen(function* () {
+      const tracing = yield* TracingService;
+      return {
+        log: (event: ComputeEventPayload) => {
+          tracing.write(Obj.make(ComputeEvent, { payload: event }));
+        },
+        nodeId: undefined,
+      };
+    }),
+  );
 }
 
 export const logCustomEvent = (data: any) =>
   Effect.gen(function* () {
-    const logger = yield* EventLogger;
+    const logger = yield* ComputeEventLogger;
     if (!logger.nodeId) {
       throw new Error('logCustomEvent must be called within a node compute function');
     }
@@ -67,7 +95,10 @@ export const createDefectLogger = <A, E, R>(): ((self: Effect.Effect<A, E, R>) =
     }),
   );
 
-export const createEventLogger = (level: LogLevel, message: string = 'event'): Context.Tag.Service<EventLogger> => {
+export const createEventLogger = (
+  level: LogLevel,
+  message: string = 'event',
+): Context.Tag.Service<ComputeEventLogger> => {
   const logFunction = (
     {
       [LogLevel.WARN]: log.warn,
@@ -79,7 +110,7 @@ export const createEventLogger = (level: LogLevel, message: string = 'event'): C
   )[level];
   invariant(logFunction);
   return {
-    log: (event: ComputeEvent) => {
+    log: (event: ComputeEventPayload) => {
       logFunction(message, event);
     },
     nodeId: undefined,

package/src/services/index.ts

@@ -2,11 +2,11 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './ai';
 export * from './database';
 export * from './queues';
 export * from './service-container';
 export * from './credentials';
 export * from './tracing';
 export * from './event-logger';
-export * from './function-call-service';
+export * from './remote-function-execution-service';
+export * from './local-function-execution';

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,36 +2,76 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Context, Layer } from 'effect';
+import { Context, Effect, Layer } from 'effect';
 
-import type { Queue, QueueFactory } from '@dxos/echo-db';
+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,
   {
     /**
      * API to access the queues.
      */
-    readonly queues: QueueFactory;
+    readonly queues: QueueAPI;
 
     /**
      * 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, {
-    get queues(): QueueFactory {
-      throw new Error('Queues not available');
+    queues: {
+      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,65 +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 { 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;
-}
+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',
-};
+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 };
 
@@ -74,23 +74,28 @@ export class ServiceContainer {
     return this;
   }
 
-  getService<T extends Context.Tag<any, any>>(tag: T): Context.Tag.Service<T> {
+  getService<Id, T>(tag: Context.Tag<Id, T>): T {
     const serviceKey = SERVICE_MAPPING[tag.key];
     const service = serviceKey != null ? this._services[serviceKey] : undefined;
     if (!service) {
       throw new Error(`Service not available: ${tag.key}`);
     }
-    return service as Context.Tag.Service<T>;
+
+    return service as T;
   }
 
   clone(): 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)
@@ -98,10 +103,10 @@ 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(),
+      RemoteFunctionExecutionService,
+      this._services.functionCallService ?? RemoteFunctionExecutionService.mock(),
     );
 
     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';