@dxos/functions 0.8.4-main.5acf9ea → 0.8.4-main.5ad4a44

package/src/handler.ts

@@ -2,16 +2,21 @@
 // Copyright 2023 DXOS.org
 //
 
-import { Schema, type Context, type Effect } from 'effect';
-
-import { type AiServiceClient } from '@dxos/ai';
-// import { type Space } from '@dxos/client/echo';
-import type { EchoDatabase } from '@dxos/echo-db';
-import { type HasId } from '@dxos/echo-schema';
-import { type SpaceId, type DXN } from '@dxos/keys';
+import type * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import type * as Types from 'effect/Types';
+
+import { Obj, Type } from '@dxos/echo';
+import { type HasId } from '@dxos/echo/internal';
+import { type EchoDatabase } from '@dxos/echo-db';
+import { assertArgument } from '@dxos/invariant';
+import { type DXN, type SpaceId } from '@dxos/keys';
 import { type QueryResult } from '@dxos/protocols';
 
-import type { Services } from './services';
+import { FunctionType } from './schema';
+import { type Services } from './services';
+import { getUserFunctionIdInMetadata, setUserFunctionIdInMetadata } from './url';
 
 // TODO(burdon): Model after http request. Ref Lambda/OpenFaaS.
 // https://docs.aws.amazon.com/lambda/latest/dg/typescript-handler.html
@@ -44,8 +49,6 @@ export interface FunctionContext {
    */
   space: SpaceAPI | undefined;
 
-  ai: AiServiceClient;
-
   /**
    * Resolves a service available to the function.
    * @throws if the service is not available.
@@ -87,22 +90,41 @@ const __assertFunctionSpaceIsCompatibleWithTheClientSpace = () => {
   // const _: SpaceAPI = {} as Space;
 };
 
-export type FunctionDefinition<T = {}, O = any> = {
+const typeId = Symbol.for('@dxos/functions/FunctionDefinition');
+
+export type FunctionDefinition<T = any, O = any> = {
+  [typeId]: true;
+  key: string;
   name: string;
   description?: string;
   inputSchema: Schema.Schema<T, any>;
   outputSchema?: Schema.Schema<O, any>;
   handler: FunctionHandler<T, O>;
+  meta?: {
+    /**
+     * Tools that are projected from functions have this annotation.
+     *
+     * deployedFunctionId:
+     * - Backend deployment ID assigned by the EDGE function service (typically a UUID).
+     * - Used for remote invocation via `FunctionInvocationService` → `RemoteFunctionExecutionService`.
+     * - Persisted on the corresponding ECHO `FunctionType` object's metadata under the
+     *   `FUNCTIONS_META_KEY` and retrieved with `getUserFunctionIdInMetadata`.
+     */
+    deployedFunctionId?: string;
+  };
 };
 
-// TODO(dmaretskyi): Bind input type to function handler.
-export const defineFunction = <T, O>({
-  name,
-  description,
-  inputSchema,
-  outputSchema = Schema.Any,
-  handler,
-}: FunctionDefinition<T, O>): FunctionDefinition<T, O> => {
+// TODO(dmaretskyi): Output type doesn't get typechecked.
+export const defineFunction: {
+  <I, O>(params: {
+    key: string;
+    name: string;
+    description?: string;
+    inputSchema: Schema.Schema<I, any>;
+    outputSchema?: Schema.Schema<O, any>;
+    handler: Types.NoInfer<FunctionHandler<I, O>>;
+  }): FunctionDefinition<I, O>;
+} = ({ key, name, description, inputSchema, outputSchema = Schema.Any, handler }) => {
   if (!Schema.isSchema(inputSchema)) {
     throw new Error('Input schema must be a valid schema');
   }
@@ -110,11 +132,94 @@ export const defineFunction = <T, O>({
     throw new Error('Handler must be a function');
   }
 
+  // Captures the function definition location.
+  const limit = Error.stackTraceLimit;
+  Error.stackTraceLimit = 2;
+  const traceError = new Error();
+  Error.stackTraceLimit = limit;
+  let cache: false | string = false;
+  const captureStackTrace = () => {
+    if (cache !== false) {
+      return cache;
+    }
+    if (traceError.stack !== undefined) {
+      const stack = traceError.stack.split('\n');
+      if (stack[2] !== undefined) {
+        cache = stack[2].trim();
+        return cache;
+      }
+    }
+  };
+
+  const handlerWithSpan = (...args: any[]) => {
+    const result = (handler as any)(...args);
+    if (Effect.isEffect(result)) {
+      return Effect.withSpan(result, `${key ?? name}`, {
+        captureStackTrace,
+      });
+    }
+    return result;
+  };
+
   return {
+    [typeId]: true,
+    key,
     name,
     description,
     inputSchema,
     outputSchema,
-    handler,
+    handler: handlerWithSpan,
+  };
+};
+
+export const FunctionDefinition = {
+  make: defineFunction,
+  isFunction: (value: unknown): value is FunctionDefinition.Any => {
+    return typeof value === 'object' && value !== null && Symbol.for('@dxos/functions/FunctionDefinition') in value;
+  },
+  serialize: (functionDef: FunctionDefinition.Any): FunctionType => {
+    assertArgument(FunctionDefinition.isFunction(functionDef), 'functionDef');
+    return serializeFunction(functionDef);
+  },
+  deserialize: (functionObj: FunctionType): FunctionDefinition.Any => {
+    assertArgument(Obj.instanceOf(FunctionType, functionObj), 'functionObj');
+    return deserializeFunction(functionObj);
+  },
+};
+export declare namespace FunctionDefinition {
+  export type Any = FunctionDefinition<any, any>;
+  export type Input<T extends FunctionDefinition> = T extends FunctionDefinition<infer I, any> ? I : never;
+  export type Output<T extends FunctionDefinition> = T extends FunctionDefinition<any, infer O> ? O : never;
+}
+
+export const serializeFunction = (functionDef: FunctionDefinition<any, any>): FunctionType => {
+  const fn = Obj.make(FunctionType, {
+    key: functionDef.key,
+    name: functionDef.name,
+    version: '0.1.0',
+    description: functionDef.description,
+    inputSchema: Type.toJsonSchema(functionDef.inputSchema),
+    outputSchema: !functionDef.outputSchema ? undefined : Type.toJsonSchema(functionDef.outputSchema),
+  });
+  if (functionDef.meta?.deployedFunctionId) {
+    setUserFunctionIdInMetadata(Obj.getMeta(fn), functionDef.meta.deployedFunctionId);
+  }
+  return fn;
+};
+
+export const deserializeFunction = (functionObj: FunctionType): FunctionDefinition<unknown, unknown> => {
+  return {
+    [typeId]: true,
+    // TODO(dmaretskyi): Fix key.
+    key: functionObj.key ?? functionObj.name,
+    name: functionObj.name,
+    description: functionObj.description,
+    inputSchema: !functionObj.inputSchema ? Schema.Unknown : Type.toEffectSchema(functionObj.inputSchema),
+    outputSchema: !functionObj.outputSchema ? undefined : Type.toEffectSchema(functionObj.outputSchema),
+    // TODO(dmaretskyi): This should throw error.
+    handler: () => {},
+    meta: {
+      deployedFunctionId: getUserFunctionIdInMetadata(Obj.getMeta(functionObj)),
+    },
   };
 };

package/src/index.ts

@@ -2,13 +2,13 @@
 // Copyright 2024 DXOS.org
 //
 
+export * from './errors';
 export * from './handler';
 export * from './schema';
 export * from './trace';
 export * from './types';
 export * from './url';
+export * from './triggers';
 export * from './services';
 export * from './executor';
-export * from './errors';
-
-// Blow up cache
+export * as exampleFunctions from './examples';

package/src/schema.ts

@@ -2,12 +2,14 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Schema } from 'effect';
+import * as Schema from 'effect/Schema';
 
 import { Type } from '@dxos/echo';
-import { JsonSchemaType, LabelAnnotation, Ref } from '@dxos/echo-schema';
+import { JsonSchemaType, LabelAnnotation, Ref } from '@dxos/echo/internal';
 import { DataType } from '@dxos/schema';
 
+// TODO(burdon): Create namespace and remove Type suffix.
+
 /**
  * Source script.
  */
@@ -32,6 +34,17 @@ export interface ScriptType extends Schema.Schema.Type<typeof ScriptType> {}
  * Function deployment.
  */
 export const FunctionType = Schema.Struct({
+  /**
+   * Global registry ID.
+   * NOTE: The `key` property refers to the original registry entry.
+   */
+  // TODO(burdon): Create Format type for DXN-like ids, such as this and schema type.
+  // TODO(dmaretskyi): Consider making it part of ECHO meta.
+  // TODO(dmaretskyi): Make required.
+  key: Schema.optional(Schema.String).annotations({
+    description: 'Unique registration key for the blueprint',
+  }),
+
   // TODO(burdon): Rename to id/uri?
   name: Schema.NonEmptyString,
   version: Schema.String,
@@ -54,4 +67,5 @@ export const FunctionType = Schema.Struct({
   }),
   LabelAnnotation.set(['name']),
 );
+
 export interface FunctionType extends Schema.Schema.Type<typeof FunctionType> {}

package/src/services/credentials.ts

@@ -2,9 +2,20 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Context, Effect, Layer } from 'effect';
+import * as HttpClient from '@effect/platform/HttpClient';
+import * as HttpClientRequest from '@effect/platform/HttpClientRequest';
+import type * as Config from 'effect/Config';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Redacted from 'effect/Redacted';
 
-type CredentialQuery = {
+import { Query } from '@dxos/echo';
+import { DataType } from '@dxos/schema';
+
+import { DatabaseService } from './database';
+
+export type CredentialQuery = {
   service?: string;
 };
 
@@ -32,14 +43,70 @@ export class CredentialsService extends Context.Tag('@dxos/functions/Credentials
     getCredential: (query: CredentialQuery) => Promise<ServiceCredential>;
   }
 >() {
-  static configuredLayer = (credentials: ServiceCredential[]) =>
-    Layer.succeed(CredentialsService, new ConfiguredCredentialsService(credentials));
-
   static getCredential = (query: CredentialQuery): Effect.Effect<ServiceCredential, never, CredentialsService> =>
     Effect.gen(function* () {
       const credentials = yield* CredentialsService;
       return yield* Effect.promise(() => credentials.getCredential(query));
     });
+
+  static getApiKey = (query: CredentialQuery): Effect.Effect<Redacted.Redacted<string>, never, CredentialsService> =>
+    Effect.gen(function* () {
+      const credential = yield* CredentialsService.getCredential(query);
+      if (!credential.apiKey) {
+        throw new Error(`API key not found for service: ${query.service}`);
+      }
+      return Redacted.make(credential.apiKey);
+    });
+
+  static configuredLayer = (credentials: ServiceCredential[]) =>
+    Layer.succeed(CredentialsService, new ConfiguredCredentialsService(credentials));
+
+  static layerConfig = (credentials: { service: string; apiKey: Config.Config<Redacted.Redacted<string>> }[]) =>
+    Layer.effect(
+      CredentialsService,
+      Effect.gen(function* () {
+        const serviceCredentials = yield* Effect.forEach(credentials, ({ service, apiKey }) =>
+          Effect.gen(function* () {
+            return {
+              service,
+              apiKey: Redacted.value(yield* apiKey),
+            };
+          }),
+        );
+
+        return new ConfiguredCredentialsService(serviceCredentials);
+      }),
+    );
+
+  static layerFromDatabase = () =>
+    Layer.effect(
+      CredentialsService,
+      Effect.gen(function* () {
+        const dbService = yield* DatabaseService;
+        const queryCredentials = async (query: CredentialQuery): Promise<ServiceCredential[]> => {
+          const { objects: accessTokens } = await dbService.db.query(Query.type(DataType.AccessToken)).run();
+          return accessTokens
+            .filter((accessToken) => accessToken.source === query.service)
+            .map((accessToken) => ({
+              service: accessToken.source,
+              apiKey: accessToken.token,
+            }));
+        };
+        return {
+          getCredential: async (query) => {
+            const credentials = await queryCredentials(query);
+            if (credentials.length === 0) {
+              throw new Error(`Credential not found for service: ${query.service}`);
+            }
+
+            return credentials[0];
+          },
+          queryCredentials: async (query) => {
+            return queryCredentials(query);
+          },
+        };
+      }),
+    );
 }
 
 export class ConfiguredCredentialsService implements Context.Tag.Service<CredentialsService> {
@@ -59,6 +126,19 @@ export class ConfiguredCredentialsService implements Context.Tag.Service<Credent
     if (!credential) {
       throw new Error(`Credential not found for service: ${query.service}`);
     }
+
     return credential;
   }
 }
+
+/**
+ * Maps the request to include the API key from the credential.
+ */
+export const withAuthorization = (query: CredentialQuery, kind?: 'Bearer' | 'Basic') =>
+  HttpClient.mapRequestEffect(
+    Effect.fnUntraced(function* (request) {
+      const key = yield* CredentialsService.getApiKey(query).pipe(Effect.map(Redacted.value));
+      const authorization = kind ? `${kind} ${key}` : key;
+      return HttpClientRequest.setHeader(request, 'Authorization', authorization);
+    }),
+  );

package/src/services/database.ts

@@ -2,10 +2,27 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Context, Effect, Layer } from 'effect';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+import type * as Schema from 'effect/Schema';
 
-import type { Filter, Live, Obj, Query, Ref, Relation } from '@dxos/echo';
-import type { EchoDatabase, OneShotQueryResult, QueryResult } from '@dxos/echo-db';
+import {
+  type Filter,
+  type Live,
+  Obj,
+  ObjectNotFoundError,
+  type Query,
+  type Ref,
+  type Relation,
+  type Type,
+} from '@dxos/echo';
+import type { EchoSchema } from '@dxos/echo/internal';
+import type { EchoDatabase, FlushOptions, OneShotQueryResult, QueryResult, SchemaRegistryQuery } from '@dxos/echo-db';
+import type { SchemaRegistryPreparedQuery } from '@dxos/echo-db';
+import { promiseWithCauseCapture } from '@dxos/effect';
+import { invariant } from '@dxos/invariant';
 import type { DXN } from '@dxos/keys';
 
 export class DatabaseService extends Context.Tag('@dxos/functions/DatabaseService')<
@@ -28,27 +45,96 @@ export class DatabaseService extends Context.Tag('@dxos/functions/DatabaseServic
     };
   };
 
-  static makeLayer = (db: EchoDatabase): Layer.Layer<DatabaseService> => {
+  static layer = (db: EchoDatabase): Layer.Layer<DatabaseService> => {
     return Layer.succeed(DatabaseService, DatabaseService.make(db));
   };
 
-  static resolve: (dxn: DXN) => Effect.Effect<Obj.Any | Relation.Any, Error, DatabaseService> = Effect.fn(
-    function* (dxn) {
+  /**
+   * Resolves an object by its DXN.
+   */
+  static resolve: {
+    // No type check.
+    (dxn: DXN): Effect.Effect<Obj.Any | Relation.Any, never, DatabaseService>;
+    // Check matches schema.
+    <S extends Type.Obj.Any | Type.Relation.Any>(
+      dxn: DXN,
+      schema: S,
+    ): Effect.Effect<Schema.Schema.Type<S>, ObjectNotFoundError, DatabaseService>;
+  } = (<S extends Type.Obj.Any | Type.Relation.Any>(
+    dxn: DXN,
+    schema?: S,
+  ): Effect.Effect<Schema.Schema.Type<S>, ObjectNotFoundError, DatabaseService> =>
+    Effect.gen(function* () {
       const { db } = yield* DatabaseService;
-      return yield* Effect.tryPromise({
-        try: () =>
-          db.graph.createRefResolver({ context: { space: db.spaceId } }).resolve(dxn) as Promise<
-            Obj.Any | Relation.Any
-          >,
-        catch: (error) => error as Error,
-      });
-    },
-  );
+      const object = yield* promiseWithCauseCapture(() =>
+        db.graph
+          .createRefResolver({
+            context: {
+              space: db.spaceId,
+            },
+          })
+          .resolve(dxn),
+      );
+
+      if (!object) {
+        return yield* Effect.fail(new ObjectNotFoundError(dxn));
+      }
+      invariant(!schema || Obj.instanceOf(schema, object), 'Object type mismatch.');
+      return object as any;
+    })) as any;
 
-  static loadRef: <T>(ref: Ref.Ref<T>) => Effect.Effect<T, never, never> = Effect.fn(function* (ref) {
-    return yield* Effect.promise(() => ref.load());
+  /**
+   * Loads an object reference.
+   */
+  static load: <T>(ref: Ref.Ref<T>) => Effect.Effect<T, ObjectNotFoundError, never> = Effect.fn(function* (ref) {
+    const object = yield* promiseWithCauseCapture(() => ref.tryLoad());
+    if (!object) {
+      return yield* Effect.fail(new ObjectNotFoundError(ref.dxn));
+    }
+    return object;
   });
 
+  /**
+   * Loads an object reference option.
+   */
+  // TODO(burdon): Option?
+  static loadOption: <T>(ref: Ref.Ref<T>) => Effect.Effect<Option.Option<T>, never, never> = Effect.fn(function* (ref) {
+    const object = yield* DatabaseService.load(ref).pipe(
+      Effect.catchTag('OBJECT_NOT_FOUND', () => Effect.succeed(undefined)),
+    );
+    return Option.fromNullable(object);
+  });
+
+  // TODO(burdon): Can we create a proxy for the following methods on EchoDatabase? Use @inheritDoc?
+  // TODO(burdon): Figure out how to chain query().run();
+
+  /**
+   * @link EchoDatabase.add
+   */
+  static add = <T extends Obj.Any | Relation.Any>(obj: T): Effect.Effect<T, never, DatabaseService> =>
+    DatabaseService.pipe(Effect.map(({ db }) => db.add(obj)));
+
+  /**
+   * @link EchoDatabase.remove
+   */
+  static remove = <T extends Obj.Any | Relation.Any>(obj: T): Effect.Effect<void, never, DatabaseService> =>
+    DatabaseService.pipe(Effect.map(({ db }) => db.remove(obj)));
+
+  /**
+   * @link EchoDatabase.flush
+   */
+  static flush = (opts?: FlushOptions) =>
+    DatabaseService.pipe(Effect.flatMap(({ db }) => promiseWithCauseCapture(() => db.flush(opts))));
+
+  /**
+   * @link EchoDatabase.getObjectById
+   */
+  static getObjectById = <T extends Obj.Any | Relation.Any>(
+    id: string,
+  ): Effect.Effect<Live<T> | undefined, never, DatabaseService> => {
+    return DatabaseService.pipe(Effect.map(({ db }) => db.getObjectById(id)));
+  };
+
   /**
    * Creates a `QueryResult` object that can be subscribed to.
    */
@@ -69,6 +155,21 @@ export class DatabaseService extends Context.Tag('@dxos/functions/DatabaseServic
     <F extends Filter.Any>(filter: F): Effect.Effect<OneShotQueryResult<Live<Filter.Type<F>>>, never, DatabaseService>;
   } = (queryOrFilter: Query.Any | Filter.Any) =>
     DatabaseService.query(queryOrFilter as any).pipe(
-      Effect.flatMap((queryResult) => Effect.promise(() => queryResult.run())),
+      Effect.flatMap((queryResult) => promiseWithCauseCapture(() => queryResult.run())),
+    );
+
+  static schemaQuery = <Q extends SchemaRegistryQuery>(
+    query: Q,
+  ): Effect.Effect<SchemaRegistryPreparedQuery<EchoSchema>, never, DatabaseService> =>
+    DatabaseService.pipe(
+      Effect.map(({ db }) => db.schemaRegistry.query(query)),
+      Effect.withSpan('DatabaseService.schemaQuery'),
+    );
+
+  static runSchemaQuery = <Q extends SchemaRegistryQuery>(
+    query: Q,
+  ): Effect.Effect<EchoSchema[], never, DatabaseService> =>
+    DatabaseService.schemaQuery(query).pipe(
+      Effect.flatMap((queryResult) => promiseWithCauseCapture(() => queryResult.run())),
     );
 }

package/src/services/event-logger.ts

@@ -2,11 +2,14 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Effect, Context, Schema, Layer } from 'effect';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Schema from 'effect/Schema';
 
 import { Obj, Type } from '@dxos/echo';
 import { invariant } from '@dxos/invariant';
-import { log, LogLevel } from '@dxos/log';
+import { LogLevel, log } from '@dxos/log';
 
 import { TracingService } from './tracing';
 

package/src/services/function-invocation-service.test.ts

@@ -0,0 +1,81 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Schema from 'effect/Schema';
+
+import { AiService } from '@dxos/ai';
+
+import { defineFunction } from '../handler';
+import { TestDatabaseLayer } from '../testing';
+
+import { FunctionInvocationService } from './function-invocation-service';
+import { FunctionImplementationResolver } from './local-function-execution';
+
+const TestLayer = Layer.mergeAll(AiService.model('@anthropic/claude-opus-4-0')).pipe(
+  Layer.provideMerge(
+    Layer.mergeAll(
+      TestDatabaseLayer({
+        indexing: { vector: true },
+        types: [],
+      }),
+      FunctionInvocationService.layer,
+    ),
+  ),
+);
+
+describe('FunctionInvocationService', () => {
+  it(
+    'should be defined',
+    Effect.fnUntraced(function* () {
+      const service = yield* FunctionInvocationService;
+      expect(service).toBeDefined();
+    }, Effect.provide(TestLayer)),
+  );
+
+  it(
+    'routes to local when implementation is available',
+    Effect.fnUntraced(function* () {
+      const add = defineFunction({
+        key: 'example.org/function/add',
+        name: 'add',
+        inputSchema: Schema.Struct({ a: Schema.Number, b: Schema.Number }),
+        outputSchema: Schema.Number,
+        handler: ({ data }) => data.a + data.b,
+      });
+
+      const layer = TestLayer.pipe(Layer.provideMerge(FunctionImplementationResolver.layerTest({ functions: [add] })));
+
+      const result = yield* Effect.gen(function* () {
+        return yield* FunctionInvocationService.invokeFunction(add, { a: 2, b: 3 });
+      }).pipe(Effect.provide(layer));
+
+      expect(result).toEqual(5);
+    }),
+  );
+
+  it(
+    'routes to remote when no local implementation is found',
+    Effect.fnUntraced(function* () {
+      // This function is not deployed, so mock layer will be used.
+      const echo = defineFunction({
+        key: 'example.org/function/echo',
+        name: 'function-that-is-deployed',
+        inputSchema: Schema.Unknown,
+        outputSchema: Schema.Unknown,
+        handler: () => {},
+      });
+
+      // No resolver provided → resolveFunctionImplementation will fail → remote path is used.
+      const result = yield* Effect.gen(function* () {
+        return yield* FunctionInvocationService.invokeFunction(echo, { hello: 'world' });
+      }).pipe(Effect.provide(TestLayer));
+
+      // RemoteFunctionExecutionService.mock echos input back.
+      expect(result).toEqual({ hello: 'world', resolved: 'remote' });
+    }),
+  );
+});