@dxos/functions 0.8.4-main.ead640a → 0.8.4-main.ef1bc66f44

package/src/protocol/protocol.ts

@@ -0,0 +1,262 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as AnthropicClient from '@effect/ai-anthropic/AnthropicClient';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { AiModelResolver, AiService } from '@dxos/ai';
+import { AnthropicResolver } from '@dxos/ai/resolvers';
+import { LifecycleState, Resource } from '@dxos/context';
+import { Database, Ref, Type } from '@dxos/echo';
+import { refFromEncodedReference } from '@dxos/echo/internal';
+import { EchoClient, type EchoDatabaseImpl, type QueueFactory } from '@dxos/echo-db';
+import { runAndForwardErrors } from '@dxos/effect';
+import { assertState, failedInvariant, invariant } from '@dxos/invariant';
+import { PublicKey } from '@dxos/keys';
+import { type FunctionProtocol } from '@dxos/protocols';
+
+import { FunctionError } from '../errors';
+import { FunctionDefinition, type FunctionServices } from '../sdk';
+import { CredentialsService, FunctionInvocationService, QueueService, TracingService } from '../services';
+
+import { FunctionsAiHttpClient } from './functions-ai-http-client';
+
+/**
+ * Wraps a function handler made with `defineFunction` to a protocol that the functions-runtime expects.
+ */
+export const wrapFunctionHandler = (func: FunctionDefinition): FunctionProtocol.Func => {
+  if (!FunctionDefinition.isFunction(func)) {
+    throw new TypeError('Invalid function definition');
+  }
+
+  return {
+    meta: {
+      key: func.key,
+      name: func.name,
+      description: func.description,
+      inputSchema: Type.toJsonSchema(func.inputSchema),
+      outputSchema: func.outputSchema === undefined ? undefined : Type.toJsonSchema(func.outputSchema),
+      services: func.services,
+    },
+    handler: async ({ data, context }) => {
+      if (
+        (func.services.includes(Database.Service.key) || func.services.includes(QueueService.key)) &&
+        (!context.services.dataService || !context.services.queryService)
+      ) {
+        throw new FunctionError({
+          message: 'Services not provided: dataService, queryService',
+        });
+      }
+
+      // eslint-disable-next-line no-useless-catch
+      try {
+        if (!SchemaAST.isAnyKeyword(func.inputSchema.ast)) {
+          try {
+            Schema.validateSync(func.inputSchema)(data);
+          } catch (error) {
+            throw new FunctionError({ message: 'Invalid input schema', cause: error });
+          }
+        }
+
+        await using funcContext = await new FunctionContext(context).open();
+
+        if (func.types.length > 0) {
+          invariant(funcContext.db, 'Database is required for functions with types');
+          await funcContext.db.graph.schemaRegistry.register(func.types as Type.Entity.Any[]);
+        }
+
+        const dataWithDecodedRefs =
+          funcContext.db && !SchemaAST.isAnyKeyword(func.inputSchema.ast)
+            ? decodeRefsFromSchema(func.inputSchema.ast, data, funcContext.db)
+            : data;
+
+        let result = await func.handler({
+          // TODO(dmaretskyi): Fix the types.
+          context: context as any,
+          data: dataWithDecodedRefs,
+        });
+
+        if (Effect.isEffect(result)) {
+          result = await runAndForwardErrors(
+            (result as Effect.Effect<unknown, unknown, FunctionServices>).pipe(
+              Effect.orDie,
+              Effect.provide(funcContext.createLayer()),
+            ),
+          );
+        }
+
+        if (func.outputSchema && !SchemaAST.isAnyKeyword(func.outputSchema.ast)) {
+          Schema.validateSync(func.outputSchema)(result);
+        }
+
+        return result;
+      } catch (error) {
+        // TODO(dmaretskyi): We might do error wrapping here and add extra context.
+        throw error;
+      }
+    },
+  };
+};
+
+/**
+ * Container for services and context for a function.
+ */
+class FunctionContext extends Resource {
+  readonly context: FunctionProtocol.Context;
+  readonly client: EchoClient | undefined;
+  db: EchoDatabaseImpl | undefined;
+  queues: QueueFactory | undefined;
+
+  constructor(context: FunctionProtocol.Context) {
+    super();
+    this.context = context;
+    if (context.services.dataService && context.services.queryService) {
+      this.client = new EchoClient().connectToService({
+        dataService: context.services.dataService,
+        queryService: context.services.queryService,
+        queueService: context.services.queueService,
+      });
+    }
+  }
+
+  override async _open() {
+    await this.client?.open();
+    this.db =
+      this.client && this.context.spaceId
+        ? this.client.constructDatabase({
+            spaceId: this.context.spaceId ?? failedInvariant(),
+            spaceKey: PublicKey.fromHex(this.context.spaceKey ?? failedInvariant('spaceKey missing in context')),
+            reactiveSchemaQuery: false,
+            preloadSchemaOnOpen: false,
+          })
+        : undefined;
+
+    await this.db?.setSpaceRoot(this.context.spaceRootUrl ?? failedInvariant('spaceRootUrl missing in context'));
+    await this.db?.open();
+    this.queues =
+      this.client && this.context.spaceId ? this.client.constructQueueFactory(this.context.spaceId) : undefined;
+  }
+
+  override async _close() {
+    await this.db?.close();
+    await this.client?.close();
+  }
+
+  createLayer(): Layer.Layer<FunctionServices> {
+    assertState(this._lifecycleState === LifecycleState.OPEN, 'FunctionContext is not open');
+
+    const dbLayer = this.db ? Database.layer(this.db) : Database.notAvailable;
+    const queuesLayer = this.queues ? QueueService.layer(this.queues) : QueueService.notAvailable;
+    const credentials = dbLayer
+      ? CredentialsService.layerFromDatabase({ caching: true }).pipe(Layer.provide(dbLayer))
+      : CredentialsService.configuredLayer([]);
+    const functionInvocationService = MockedFunctionInvocationService;
+    const tracing = TracingService.layerNoop;
+
+    const aiLayer = this.context.services.functionsAiService
+      ? AiModelResolver.AiModelResolver.buildAiService.pipe(
+          Layer.provide(
+            AnthropicResolver.make().pipe(
+              Layer.provide(
+                AnthropicClient.layer({
+                  // Note: It doesn't matter what is base url here, it will be proxied to ai gateway in edge.
+                  apiUrl: 'http://internal/provider/anthropic',
+                }).pipe(Layer.provide(FunctionsAiHttpClient.layer(this.context.services.functionsAiService))),
+              ),
+            ),
+          ),
+        )
+      : AiService.notAvailable;
+
+    return Layer.mergeAll(
+      dbLayer, //
+      queuesLayer,
+      credentials,
+      functionInvocationService,
+      aiLayer,
+      tracing,
+    );
+  }
+}
+
+const MockedFunctionInvocationService = Layer.succeed(FunctionInvocationService, {
+  invokeFunction: () => Effect.die('Calling functions from functions is not implemented yet.'),
+  resolveFunction: () => Effect.die('Not implemented.'),
+});
+
+const decodeRefsFromSchema = (ast: SchemaAST.AST, value: unknown, db: EchoDatabaseImpl): unknown => {
+  if (value == null) {
+    return value;
+  }
+
+  const encoded = SchemaAST.encodedBoundAST(ast);
+  if (Ref.isRefType(encoded)) {
+    if (Ref.isRef(value)) {
+      return value;
+    }
+
+    if (typeof value === 'object' && value !== null && typeof (value as any)['/'] === 'string') {
+      const resolver = db.graph.createRefResolver({ context: { space: db.spaceId } });
+      return refFromEncodedReference(value as any, resolver);
+    }
+
+    return value;
+  }
+
+  switch (encoded._tag) {
+    case 'TypeLiteral': {
+      if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return value;
+      }
+      const result: Record<string, unknown> = { ...(value as any) };
+      for (const prop of SchemaAST.getPropertySignatures(encoded)) {
+        const key = prop.name.toString();
+        if (key in result) {
+          result[key] = decodeRefsFromSchema(prop.type, (result as any)[key], db);
+        }
+      }
+      return result;
+    }
+
+    case 'TupleType': {
+      if (!Array.isArray(value)) {
+        return value;
+      }
+
+      // For arrays, effect uses TupleType with empty elements and a single rest element.
+      if (encoded.elements.length === 0 && encoded.rest.length === 1) {
+        const elementType = encoded.rest[0].type;
+        return (value as unknown[]).map((item) => decodeRefsFromSchema(elementType, item, db));
+      }
+
+      return value;
+    }
+
+    case 'Union': {
+      // Optional values are represented as union with undefined.
+      const nonUndefined = encoded.types.filter((t) => !SchemaAST.isUndefinedKeyword(t));
+      if (nonUndefined.length === 1) {
+        return decodeRefsFromSchema(nonUndefined[0], value, db);
+      }
+
+      // For other unions we can't safely pick a branch without validating.
+      return value;
+    }
+
+    case 'Suspend': {
+      return decodeRefsFromSchema(encoded.f(), value, db);
+    }
+
+    case 'Refinement': {
+      return decodeRefsFromSchema(encoded.from, value, db);
+    }
+
+    default: {
+      return value;
+    }
+  }
+};

package/src/sdk.ts

@@ -0,0 +1,289 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import type * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { type AiService } from '@dxos/ai';
+import { Obj, Type } from '@dxos/echo';
+import { type Database } from '@dxos/echo';
+import { assertArgument, failedInvariant } from '@dxos/invariant';
+import { Operation } from '@dxos/operation';
+
+import {
+  type CredentialsService,
+  type FunctionInvocationService,
+  type QueueService,
+  type TracingService,
+} from './services';
+import { Function } from './types';
+import { getUserFunctionIdInMetadata, setUserFunctionIdInMetadata } from './types';
+
+// TODO(burdon): Model after http request. Ref Lambda/OpenFaaS.
+// https://docs.aws.amazon.com/lambda/latest/dg/typescript-handler.html
+// https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml/#functions
+// https://www.npmjs.com/package/aws-lambda
+
+/**
+ * Services that are provided at the function call site by the caller.
+ */
+export type InvocationServices = TracingService;
+
+/**
+ * Services that are available to invoked functions.
+ */
+export type FunctionServices =
+  | InvocationServices
+  | AiService.AiService
+  | CredentialsService
+  | Database.Service
+  | QueueService
+  | FunctionInvocationService;
+
+/**
+ * Function handler.
+ */
+export type FunctionHandler<TData = {}, TOutput = any, S extends FunctionServices = FunctionServices> = (params: {
+  /**
+   * Context available to the function.
+   */
+  context: FunctionContext;
+
+  /**
+   * Data passed as the input to the function.
+   * Must match the function's input schema.
+   * This will be the payload from the trigger or other data passed into the function in a workflow.
+   */
+  data: TData;
+}) => TOutput | Promise<TOutput> | Effect.Effect<TOutput, any, S>;
+
+/**
+ * Function context.
+ */
+export interface FunctionContext {
+  // TODO(dmaretskyi): Consider what we should put into context.
+}
+
+const typeId = Symbol.for('@dxos/functions/FunctionDefinition');
+
+export type FunctionDefinition<T = any, O = any, S extends FunctionServices = FunctionServices> = {
+  [typeId]: true;
+  key: string;
+  name: string;
+  description?: string;
+  inputSchema: Schema.Schema<T, any>;
+  outputSchema?: Schema.Schema<O, any>;
+
+  /**
+   * List of types the function uses.
+   * This is used to ensure that the types are available when the function is executed.
+   */
+  types: readonly Type.Entity.Any[];
+
+  /**
+   * Keys of the required services.
+   */
+  services: readonly string[];
+
+  handler: FunctionHandler<T, O, S>;
+  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 `Function.Function` object's metadata under the
+     *   `FUNCTIONS_META_KEY` and retrieved with `getUserFunctionIdInMetadata`.
+     */
+    deployedFunctionId?: string;
+  };
+};
+
+export declare namespace FunctionDefinition {
+  export type Any = FunctionDefinition<any, any, any>;
+  export type Input<T extends Any> = T extends FunctionDefinition<infer I, infer _O, infer _S> ? I : never;
+  export type Output<T extends Any> = T extends FunctionDefinition<infer _I, infer O, infer _S> ? O : never;
+  export type Services<T extends Any> = T extends FunctionDefinition<infer _I, infer _O, infer S> ? S : never;
+}
+
+export type FunctionProps<T, O> = {
+  key: string;
+  name: string;
+  description?: string;
+  inputSchema: Schema.Schema<T, any>;
+  outputSchema?: Schema.Schema<O, any>;
+
+  /**
+   * List of types the function uses.
+   * This is used to ensure that the types are available when the function is executed.
+   */
+  types?: readonly Type.Entity.Any[];
+  // TODO(dmaretskyi): This currently doesn't cause a compile-time error if the handler requests a service that is not specified
+  services?: readonly Context.Tag<any, any>[];
+
+  handler: FunctionHandler<T, O, FunctionServices>;
+};
+
+// TODO(dmaretskyi): Output type doesn't get typechecked.
+export const defineFunction: {
+  <I, O>(params: FunctionProps<I, O>): FunctionDefinition<I, O, FunctionServices>;
+} = ({ key, name, description, inputSchema, outputSchema = Schema.Any, handler, types, services }) => {
+  if (!Schema.isSchema(inputSchema)) {
+    throw new Error('Input schema must be a valid schema');
+  }
+  if (typeof handler !== 'function') {
+    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: handlerWithSpan,
+    types: types ?? [],
+    services: !services ? [] : getServiceKeys(services),
+  } satisfies FunctionDefinition.Any;
+};
+
+const getServiceKeys = (services: readonly Context.Tag<any, any>[]) => {
+  return services.map((tag: any) => {
+    if (typeof tag.key === 'string') {
+      return tag.key;
+    }
+    failedInvariant();
+  });
+};
+
+/**
+ * Converts a FunctionDefinition to an OperationDefinition with handler.
+ * The function handler is adapted to the OperationHandler format.
+ *
+ * Note: FunctionDefinition stores service keys as strings, not Tag types,
+ * so we can't use Operation.withHandler's type inference here.
+ */
+export const toOperation = <T, O, S extends FunctionServices = FunctionServices>(
+  functionDef: FunctionDefinition<T, O, S>,
+): Operation.Definition<T, O> & { handler: Operation.Handler<T, O, any, S> } => {
+  const op = Operation.make({
+    schema: {
+      input: functionDef.inputSchema,
+      output: functionDef.outputSchema ?? Schema.Any,
+    },
+    meta: {
+      key: functionDef.key,
+      name: functionDef.name,
+      description: functionDef.description,
+    },
+  });
+
+  // Adapt FunctionHandler signature to OperationHandler format.
+  // FunctionHandler expects { context, data }, OperationHandler expects just input.
+  const operationHandler: Operation.Handler<T, O, any, S> = (input: T) => {
+    const result = functionDef.handler({
+      context: {} as FunctionContext,
+      data: input,
+    });
+
+    // Convert Promise or plain value to Effect.
+    if (Effect.isEffect(result)) {
+      return result;
+    }
+    if (result instanceof Promise) {
+      return Effect.tryPromise(() => result);
+    }
+    return Effect.succeed(result as O);
+  };
+
+  // Manually attach handler since FunctionDefinition stores service keys as strings,
+  // not Tag types, so withHandler's type inference doesn't apply.
+  return {
+    ...op,
+    handler: operationHandler,
+  };
+};
+
+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): Function.Function => {
+    assertArgument(FunctionDefinition.isFunction(functionDef), 'functionDef');
+    return serializeFunction(functionDef);
+  },
+  deserialize: (functionObj: Function.Function): FunctionDefinition.Any => {
+    assertArgument(Obj.instanceOf(Function.Function, functionObj), 'functionObj');
+    return deserializeFunction(functionObj);
+  },
+  toOperation,
+};
+
+export const serializeFunction = (functionDef: FunctionDefinition.Any): Function.Function => {
+  const fn = Function.make({
+    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),
+    services: functionDef.services,
+  });
+  if (functionDef.meta?.deployedFunctionId) {
+    Obj.change(fn, (fn) => setUserFunctionIdInMetadata(Obj.getMeta(fn), functionDef.meta!.deployedFunctionId!));
+  }
+  return fn;
+};
+
+export const deserializeFunction = (functionObj: Function.Function): 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: () => {},
+    services: functionObj.services ?? [],
+    types: [],
+    meta: {
+      deployedFunctionId: getUserFunctionIdInMetadata(Obj.getMeta(functionObj)),
+    },
+  };
+};

package/src/services/credentials.ts

@@ -11,9 +11,8 @@ import * as Layer from 'effect/Layer';
 import * as Redacted from 'effect/Redacted';
 
 import { Query } from '@dxos/echo';
-import { DataType } from '@dxos/schema';
-
-import { DatabaseService } from './database';
+import { Database } from '@dxos/echo';
+import { AccessToken } from '@dxos/types';
 
 export type CredentialQuery = {
   service?: string;
@@ -61,7 +60,12 @@ export class CredentialsService extends Context.Tag('@dxos/functions/Credentials
   static configuredLayer = (credentials: ServiceCredential[]) =>
     Layer.succeed(CredentialsService, new ConfiguredCredentialsService(credentials));
 
-  static layerConfig = (credentials: { service: string; apiKey: Config.Config<Redacted.Redacted<string>> }[]) =>
+  static layerConfig = (
+    credentials: {
+      service: string;
+      apiKey: Config.Config<Redacted.Redacted<string>>;
+    }[],
+  ) =>
     Layer.effect(
       CredentialsService,
       Effect.gen(function* () {
@@ -78,20 +82,34 @@ export class CredentialsService extends Context.Tag('@dxos/functions/Credentials
       }),
     );
 
-  static layerFromDatabase = () =>
+  static layerFromDatabase = ({ caching = false }: { caching?: boolean } = {}) =>
     Layer.effect(
       CredentialsService,
       Effect.gen(function* () {
-        const dbService = yield* DatabaseService;
+        const dbService = yield* Database.Service;
+        const cache = new Map<string, ServiceCredential[]>();
+
         const queryCredentials = async (query: CredentialQuery): Promise<ServiceCredential[]> => {
-          const { objects: accessTokens } = await dbService.db.query(Query.type(DataType.AccessToken)).run();
-          return accessTokens
+          const cacheKey = JSON.stringify(query);
+          if (caching && cache.has(cacheKey)) {
+            return cache.get(cacheKey)!;
+          }
+
+          const accessTokens = await dbService.db.query(Query.type(AccessToken.AccessToken)).run();
+          const credentials = accessTokens
             .filter((accessToken) => accessToken.source === query.service)
             .map((accessToken) => ({
               service: accessToken.source,
               apiKey: accessToken.token,
             }));
+
+          if (caching) {
+            cache.set(cacheKey, credentials);
+          }
+
+          return credentials;
         };
+
         return {
           getCredential: async (query) => {
             const credentials = await queryCredentials(query);
@@ -132,13 +150,10 @@ export class ConfiguredCredentialsService implements Context.Tag.Service<Credent
 }
 
 /**
- * Maps the request to include the API key from the credential.
+ * Maps the request to include the given token in the Authorization header.
  */
-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);
-    }),
-  );
+export const withAuthorization = (token: string, kind?: 'Bearer' | 'Basic') =>
+  HttpClient.mapRequest((request) => {
+    const authorization = kind ? `${kind} ${token}` : token;
+    return HttpClientRequest.setHeader(request, 'Authorization', authorization);
+  });

package/src/services/event-logger.ts

@@ -17,12 +17,18 @@ export const ComputeEventPayload = Schema.Union(
   Schema.Struct({
     type: Schema.Literal('begin-compute'),
     nodeId: Schema.String,
-    inputs: Schema.Record({ key: Schema.String, value: Schema.Any }),
+    /**
+     * Names of the inputs begin computed.
+     */
+    inputs: Schema.Array(Schema.String),
   }),
   Schema.Struct({
     type: Schema.Literal('end-compute'),
     nodeId: Schema.String,
-    outputs: Schema.Record({ key: Schema.String, value: Schema.Any }),
+    /**
+     * Names of the outputs computed.
+     */
+    outputs: Schema.Array(Schema.String),
   }),
   Schema.Struct({
     type: Schema.Literal('compute-input'),
@@ -46,7 +52,7 @@ export type ComputeEventPayload = Schema.Schema.Type<typeof ComputeEventPayload>
 
 export const ComputeEvent = Schema.Struct({
   payload: ComputeEventPayload,
-}).pipe(Type.Obj({ typename: 'dxos.org/type/ComputeEvent', version: '0.1.0' }));
+}).pipe(Type.object({ typename: 'dxos.org/type/ComputeEvent', version: '0.1.0' }));
 
 /**
  * Logs event for the compute workflows.
@@ -69,7 +75,7 @@ export class ComputeEventLogger extends Context.Tag('@dxos/functions/ComputeEven
       const tracing = yield* TracingService;
       return {
         log: (event: ComputeEventPayload) => {
-          tracing.write(Obj.make(ComputeEvent, { payload: event }));
+          tracing.write(Obj.make(ComputeEvent, { payload: event }), tracing.getTraceContext());
         },
         nodeId: undefined,
       };