@dxos/functions 0.8.3 → 0.8.4-main.1da679c

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

@@ -0,0 +1,127 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Context, Effect, Layer, Schema } from 'effect';
+
+import { todo } from '@dxos/debug';
+import { log } from '@dxos/log';
+
+import { FunctionError, FunctionNotFoundError } 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(functionDef: FunctionDefinition<any, any>, input: unknown): Effect.Effect<unknown, never, Services>;
+  }
+>() {
+  /**
+   * @deprecated Use layerLive instead.
+   */
+  static layer = Layer.succeed(LocalFunctionExecutionService, {
+    invokeFunction: (functionDef, input) => invokeFunction(functionDef, input),
+  });
+
+  static layerLive = Layer.effect(
+    LocalFunctionExecutionService,
+    Effect.gen(function* () {
+      const resolver = yield* FunctionImplementationResolver;
+      return {
+        invokeFunction: Effect.fn('invokeFunction')(function* (functionDef, input) {
+          // TODO(dmaretskyi): Better error types
+          const resolved = yield* resolver.resolveFunctionImplementation(functionDef).pipe(Effect.orDie);
+          return yield* invokeFunction(resolved, input);
+        }),
+      };
+    }),
+  );
+
+  static invokeFunction: <F extends FunctionDefinition.Any>(
+    functionDef: F,
+    input: FunctionDefinition.Input<F>,
+  ) => Effect.Effect<FunctionDefinition.Output<F>, never, Services | LocalFunctionExecutionService> =
+    Effect.serviceFunctionEffect(LocalFunctionExecutionService, (_) => _.invokeFunction as any);
+}
+
+const invokeFunction = (
+  functionDef: FunctionDefinition<any, any>,
+  input: any,
+): Effect.Effect<unknown, never, Services> =>
+  Effect.gen(function* () {
+    // Assert input matches schema
+    try {
+      const assertInput = functionDef.inputSchema.pipe(Schema.asserts);
+      (assertInput as any)(input);
+    } catch (e) {
+      throw new FunctionError({ message: 'Invalid function input', context: { name: functionDef.name }, cause: e });
+    }
+
+    const context: FunctionContext = {
+      space: undefined,
+      getService: () => todo(),
+      getSpace: async (_spaceId: any) => {
+        throw new Error('Not available. Use the database service instead.');
+      },
+    };
+
+    log.info('Invoking function', { name: functionDef.name, input });
+
+    // TODO(dmaretskyi): This should be delegated to a function invoker service.
+    const data = yield* Effect.gen(function* () {
+      const result = functionDef.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({ context: { name: functionDef.name }, cause: defect })),
+      ),
+    );
+
+    log.info('Function completed', { name: functionDef.name, input, data });
+
+    // Assert output matches schema
+    try {
+      const assertOutput = functionDef.outputSchema?.pipe(Schema.asserts);
+      (assertOutput as any)(data);
+    } catch (e) {
+      throw new FunctionError({ message: 'Invalid function output', context: { name: functionDef.name }, cause: e });
+    }
+
+    return data;
+  }).pipe(Effect.withSpan('invokeFunction', { attributes: { name: functionDef.name } }));
+
+export class FunctionImplementationResolver extends Context.Tag('@dxos/functions/FunctionImplementationResolver')<
+  FunctionImplementationResolver,
+  {
+    resolveFunctionImplementation(
+      functionDef: FunctionDefinition<any, any>,
+    ): Effect.Effect<FunctionDefinition<any, any>, FunctionNotFoundError>;
+  }
+>() {
+  static layerTest = ({ functions }: { functions: FunctionDefinition<any, any>[] }) =>
+    Layer.succeed(FunctionImplementationResolver, {
+      resolveFunctionImplementation: (functionDef) => {
+        const resolved = functions.find((f) => f.name === functionDef.name);
+        if (!resolved) {
+          return Effect.fail(new FunctionNotFoundError(functionDef.name));
+        }
+        return Effect.succeed(resolved);
+      },
+    });
+}

package/src/services/queues.ts

@@ -2,36 +2,81 @@
 // 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)));
+
+  static append = <T extends Obj.Any | Relation.Any = Obj.Any | Relation.Any>(
+    queue: Queue<T>,
+    objects: T[],
+  ): Effect.Effect<void> => Effect.promise(() => queue.append(objects));
+}
+
+/**
+ * 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/remote-function-execution-service.ts

@@ -0,0 +1,46 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Context, Layer } from 'effect';
+
+import type { SpaceId } from '@dxos/keys';
+
+import { getInvocationUrl } from '../url';
+
+/**
+ * Allows calling into other functions.
+ */
+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<RemoteFunctionExecutionService> {
+    return {
+      callFunction: async (deployedFunctionId: string, input: any) => {
+        const url = getInvocationUrl(deployedFunctionId, baseUrl, { spaceId });
+        const result = await fetch(url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(input),
+        });
+        if (result.status >= 300 || result.status < 200) {
+          throw new Error('Failed to invoke function', { cause: new Error(`HTTP error: ${await result.text()}`) });
+        }
+        return await result.json();
+      },
+    };
+  }
+
+  static mock = (): Context.Tag.Service<RemoteFunctionExecutionService> => {
+    return {
+      callFunction: async (deployedFunctionId: string, input: any) => {
+        return input;
+      },
+    };
+  };
+
+  static mockLayer = Layer.succeed(RemoteFunctionExecutionService, RemoteFunctionExecutionService.mock());
+}

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,26 +2,139 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Context } from 'effect';
+import { Context, Effect, Layer } from 'effect';
 
-import type { AnyEchoObject } from '@dxos/echo-schema';
+import { AgentStatus } from '@dxos/ai';
+import { Obj } from '@dxos/echo';
+import type { Queue } from '@dxos/echo-db';
+import type { ObjectId } from '@dxos/echo-schema';
+import { log } from '@dxos/log';
+import { DataType } from '@dxos/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,
   {
+    /**
+     * Gets the parent message ID.
+     */
+    getTraceContext: () => TracingService.TraceContext;
+
     /**
      * Write an event to the tracing queue.
      * @param event - The event to write. Must be an a typed object.
      */
-    write(event: AnyEchoObject): void;
+    write: (event: Obj.Any) => void;
   }
 >() {
-  static noop: Context.Tag.Service<TracingService> = { write: () => {} };
+  static noop: Context.Tag.Service<TracingService> = { write: () => {}, getTraceContext: () => ({}) };
+
+  static layerNoop = Layer.succeed(TracingService, TracingService.noop);
 
   static console: Context.Tag.Service<TracingService> = {
     write: (event) => {
       // eslint-disable-next-line no-console
       console.log(event);
     },
+    getTraceContext: () => ({}),
   };
+
+  static layerConsole = Layer.succeed(TracingService, TracingService.console);
+
+  static layerLogInfo = () =>
+    Layer.succeed(TracingService, {
+      write: (event) => {
+        if (Obj.instanceOf(AgentStatus, event)) {
+          log.info('status', { message: event.message });
+        }
+      },
+      getTraceContext: () => ({}),
+    });
+
+  /**
+   * Creates a TracingService layer that emits events to the parent tracing service.
+   */
+  static layerSubframe = (mapContext: (currentContext: TracingService.TraceContext) => TracingService.TraceContext) =>
+    Layer.effect(
+      TracingService,
+      Effect.gen(function* () {
+        const tracing = yield* TracingService;
+        const context = mapContext(tracing.getTraceContext());
+        return {
+          write: (event) => tracing.write(event),
+          getTraceContext: () => context,
+        };
+      }),
+    );
+
+  static layerQueue = (queue: Queue) =>
+    Layer.effect(
+      TracingService,
+      Effect.gen(function* () {
+        // TODO(dmaretskyi): Batching.
+        return {
+          write: (event) => queue.append([event]),
+          getTraceContext: () => ({
+            debugInfo: {
+              queue: queue.dxn.toString(),
+            },
+          }),
+        };
+      }),
+    );
+
+  /**
+   * 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, {
+          parentMessage: tracing.getTraceContext().parentMessage,
+          toolCallId: tracing.getTraceContext().toolCallId,
+          ...data,
+        }),
+      );
+    });
+
+  static emitConverationMessage: (
+    data: Obj.MakeProps<typeof DataType.Message>,
+  ) => Effect.Effect<void, never, TracingService> = Effect.fnUntraced(function* (data) {
+    const tracing = yield* TracingService;
+    tracing.write(
+      Obj.make(DataType.Message, {
+        parentMessage: tracing.getTraceContext().parentMessage,
+        ...data,
+        properties: {
+          [MESSAGE_PROPERTY_TOOL_CALL_ID]: tracing.getTraceContext().toolCallId,
+          ...data.properties,
+        },
+      }),
+    );
+  });
 }
+
+export namespace TracingService {
+  export interface TraceContext {
+    /**
+     * If this thread sprung from a tool call, this is the ID of the message containing the tool call.
+     */
+    parentMessage?: ObjectId;
+
+    /**
+     * If the current thread is a byproduct of a tool call, this is the ID of the tool call.
+     */
+    toolCallId?: string;
+
+    debugInfo?: unknown;
+  }
+}
+
+/**
+ * Goes into {@link DataType.Message['properties']}
+ */
+export const MESSAGE_PROPERTY_TOOL_CALL_ID = 'toolCallId' as const;

package/src/testing/index.ts

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