@dxos/functions 0.8.4-main.3f58842 → 0.8.4-main.548089c

package/package.json

@@ -1,94 +1,43 @@
 {
   "name": "@dxos/functions",
-  "version": "0.8.4-main.3f58842",
-  "description": "Functions API and runtime.",
+  "version": "0.8.4-main.548089c",
+  "description": "Functions API.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
   "license": "MIT",
   "author": "info@dxos.org",
-  "sideEffects": true,
+  "sideEffects": false,
   "type": "module",
   "exports": {
-    "./bundler": {
-      "types": "./dist/types/src/bundler/index.d.ts",
-      "browser": "./dist/lib/browser/bundler/index.mjs",
-      "node": "./dist/lib/node-esm/bundler/index.mjs"
-    },
-    "./edge": {
-      "types": "./dist/types/src/edge/index.d.ts",
-      "browser": "./dist/lib/browser/edge/index.mjs",
-      "node": "./dist/lib/node-esm/edge/index.mjs"
-    },
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
       "node": "./dist/lib/node-esm/index.mjs"
-    },
-    "./testing": {
-      "types": "./dist/types/src/testing/index.d.ts",
-      "browser": "./dist/lib/browser/testing/index.mjs",
-      "node": "./dist/lib/node-esm/testing/index.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "bundler": [
-        "dist/types/src/bundler/index.d.ts"
-      ],
-      "edge": [
-        "dist/types/src/edge/index.d.ts"
-      ]
-    }
-  },
   "files": [
     "dist",
     "schema",
     "src"
   ],
   "dependencies": {
-    "@effect/platform": "0.89.0",
-    "@preact/signals-core": "^1.9.0",
-    "cron": "^3.1.6",
-    "cron-schedule": "^5.0.4",
-    "effect": "3.17.0",
-    "esbuild-wasm": "^0.16.14",
-    "express": "^4.19.2",
-    "get-port-please": "^3.1.1",
-    "i18next": "^24.2.1",
-    "iso-did": "^1.6.0",
-    "ws": "^8.14.2",
-    "@dxos/ai": "0.8.4-main.3f58842",
-    "@dxos/async": "0.8.4-main.3f58842",
-    "@dxos/client": "0.8.4-main.3f58842",
-    "@dxos/context": "0.8.4-main.3f58842",
-    "@dxos/crypto": "0.8.4-main.3f58842",
-    "@dxos/echo-db": "0.8.4-main.3f58842",
-    "@dxos/echo-pipeline": "0.8.4-main.3f58842",
-    "@dxos/echo": "0.8.4-main.3f58842",
-    "@dxos/echo-protocol": "0.8.4-main.3f58842",
-    "@dxos/echo-schema": "0.8.4-main.3f58842",
-    "@dxos/edge-client": "0.8.4-main.3f58842",
-    "@dxos/effect": "0.8.4-main.3f58842",
-    "@dxos/errors": "0.8.4-main.3f58842",
-    "@dxos/invariant": "0.8.4-main.3f58842",
-    "@dxos/keys": "0.8.4-main.3f58842",
-    "@dxos/log": "0.8.4-main.3f58842",
-    "@dxos/live-object": "0.8.4-main.3f58842",
-    "@dxos/node-std": "0.8.4-main.3f58842",
-    "@dxos/protocols": "0.8.4-main.3f58842",
-    "@dxos/util": "0.8.4-main.3f58842",
-    "@dxos/schema": "0.8.4-main.3f58842"
-  },
-  "devDependencies": {
-    "@types/express": "^4.17.17",
-    "@types/ws": "^7.4.0",
-    "@dxos/agent": "0.8.4-main.3f58842"
+    "@effect/platform": "0.92.1",
+    "effect": "3.18.3",
+    "@dxos/ai": "0.8.4-main.548089c",
+    "@dxos/errors": "0.8.4-main.548089c",
+    "@dxos/invariant": "0.8.4-main.548089c",
+    "@dxos/keys": "0.8.4-main.548089c",
+    "@dxos/log": "0.8.4-main.548089c",
+    "@dxos/node-std": "0.8.4-main.548089c",
+    "@dxos/schema": "0.8.4-main.548089c",
+    "@dxos/echo-db": "0.8.4-main.548089c",
+    "@dxos/echo": "0.8.4-main.548089c",
+    "@dxos/types": "0.8.4-main.548089c"
   },
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "gen-schema": "ts-node ./tools/schema.ts"
-  }
+  "scripts": {}
 }

package/src/errors.ts

@@ -2,12 +2,20 @@
 // Copyright 2025 DXOS.org
 //
 
-import { BaseError } from '@dxos/errors';
+import { BaseError, type BaseErrorOptions } from '@dxos/errors';
 
-export class ServiceNotAvailableError extends BaseError.extend('SERVICE_NOT_AVAILABLE') {
-  constructor(serviceName: string) {
-    super(`Service not available: ${serviceName}`);
+export class ServiceNotAvailableError extends BaseError.extend('SERVICE_NOT_AVAILABLE', 'Service not available') {
+  constructor(service: string, options?: Omit<BaseErrorOptions, 'context'>) {
+    super({ context: { service }, ...options });
   }
 }
 
-export class FunctionError extends BaseError.extend('FUNCTION_ERROR') {}
+export class FunctionNotFoundError extends BaseError.extend('FUNCTION_NOT_FOUND', 'Function not found') {
+  constructor(functionKey: string, options?: Omit<BaseErrorOptions, 'context'>) {
+    super({ context: { function: functionKey }, ...options });
+  }
+}
+
+export class FunctionError extends BaseError.extend('FUNCTION_ERROR', 'Function invocation error') {}
+
+export class TriggerStateNotFoundError extends BaseError.extend('TRIGGER_STATE_NOT_FOUND', 'Trigger state not found') {}

package/src/example/fib.ts

@@ -0,0 +1,32 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { defineFunction } from '../handler';
+
+export default defineFunction({
+  key: 'example.org/function/fib',
+  name: 'Fibonacci',
+  description: 'Function that calculates a Fibonacci number',
+  inputSchema: Schema.Struct({
+    iterations: Schema.optional(Schema.Number).annotations({
+      description: 'Number of iterations',
+      default: 100_000,
+    }),
+  }),
+  outputSchema: Schema.Struct({
+    result: Schema.String,
+  }),
+  handler: Effect.fn(function* ({ data: { iterations = 100_000 } }) {
+    let a = 0n;
+    let b = 1n;
+    for (let i = 0; i < iterations; i++) {
+      a += b;
+      b = a - b;
+    }
+    return { result: a.toString() };
+  }),
+});

package/src/example/forex-effect.ts

@@ -0,0 +1,40 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @ts-ignore
+import { S, defineFunction } from 'dxos:functions';
+import {
+  FetchHttpClient,
+  HttpClient,
+  HttpClientRequest,
+  // @ts-ignore
+} from 'https://esm.sh/@effect/platform@0.89.0?deps=effect@3.17.0&bundle=false';
+// @ts-ignore
+import { Effect, Schedule } from 'https://esm.sh/effect@3.17.0?bundle=false';
+
+export default defineFunction({
+  key: 'dxos.org/script/forex-effect',
+  name: 'Forex Effect',
+  description: 'Returns the exchange rate between two currencies.',
+
+  inputSchema: S.Struct({
+    from: S.String.annotations({ description: 'The source currency' }),
+    to: S.String.annotations({ description: 'The target currency' }),
+  }),
+
+  outputSchema: S.String.annotations({ description: 'The exchange rate between the two currencies' }),
+
+  handler: async ({ data: { from, to } }: any) =>
+    Effect.gen(function* () {
+      const res = yield* HttpClientRequest.get(`https://free.ratesdb.com/v1/rates?from=${from}&to=${to}`).pipe(
+        HttpClient.execute,
+        Effect.flatMap((res: any) => res.json),
+        Effect.timeout('1 second'),
+        Effect.retry(Schedule.exponential(1_000).pipe(Schedule.compose(Schedule.recurs(3)))),
+        Effect.scoped,
+      );
+
+      return res.data.rates[to].toString();
+    }).pipe(Effect.provide(FetchHttpClient.layer)),
+});

package/src/example/index.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { default as fib$ } from './fib';
+import { default as reply$ } from './reply';
+import { default as sleep$ } from './sleep';
+
+export namespace Example {
+  export const fib = fib$;
+  export const reply = reply$;
+  export const sleep = sleep$;
+}

package/src/example/reply.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Console from 'effect/Console';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { defineFunction } from '../handler';
+
+export default defineFunction({
+  key: 'example.org/function/reply',
+  name: 'Reply',
+  description: 'Function that echoes the input',
+  inputSchema: Schema.Any,
+  outputSchema: Schema.Any,
+  handler: Effect.fn(function* ({ data }) {
+    yield* Console.log('reply', { data });
+    return data;
+  }),
+});

package/src/example/sleep.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { defineFunction } from '../handler';
+
+export default defineFunction({
+  key: 'example.org/function/sleep',
+  name: 'Sleep',
+  description: 'Function that sleeps for a given amount of time',
+  inputSchema: Schema.Struct({
+    duration: Schema.optional(Schema.Number).annotations({
+      description: 'Milliseconds to sleep',
+      default: 100_000,
+    }),
+  }),
+  outputSchema: Schema.Void,
+  handler: Effect.fn(function* ({ data: { duration = 100_000 } }) {
+    yield* Effect.sleep(duration);
+  }),
+});

package/src/handler.ts

@@ -2,22 +2,44 @@
 // 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 QueryResult } from '@dxos/protocols';
-
-import type { Services } from './services';
+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 DatabaseService } from '@dxos/echo-db';
+import { assertArgument } from '@dxos/invariant';
+
+import {
+  type CredentialsService,
+  type FunctionInvocationService,
+  type QueueService,
+  type TracingService,
+} from './services';
+import { Function } from './types';
+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
 // 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
+  | DatabaseService
+  | QueueService
+  | FunctionInvocationService;
+
 /**
  * Function handler.
  */
@@ -33,61 +55,41 @@ export type FunctionHandler<TData = {}, TOutput = any> = (params: {
    * 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, Services>;
+}) => TOutput | Promise<TOutput> | Effect.Effect<TOutput, any, FunctionServices>;
 
 /**
  * Function context.
  */
 export interface FunctionContext {
-  /**
-   * Space from which the function was invoked.
-   */
-  space: SpaceAPI | undefined;
-
-  ai: AiServiceClient;
-
-  /**
-   * Resolves a service available to the function.
-   * @throws if the service is not available.
-   */
-  getService: <T extends Context.Tag<any, any>>(tag: T) => Context.Tag.Service<T>;
-
-  getSpace: (spaceId: SpaceId) => Promise<SpaceAPI>;
+  // TODO(dmaretskyi):
 }
 
-export interface FunctionContextAi {
-  // TODO(dmaretskyi): Refer to cloudflare AI docs for more comprehensive typedefs.
-  run(model: string, inputs: any, options?: any): Promise<any>;
-}
+const typeId = Symbol.for('@dxos/functions/FunctionDefinition');
 
-//
-// API.
-//
-
-// TODO(dmaretskyi): Temporary API to get the queues working.
-// TODO(dmaretskyi): To be replaced with integrating queues into echo.
-export interface QueuesAPI {
-  queryQueue(queue: DXN, options?: {}): Promise<QueryResult>;
-  insertIntoQueue(queue: DXN, objects: HasId[]): Promise<void>;
-}
-
-/**
- * Space interface available to functions.
- */
-export interface SpaceAPI {
-  get id(): SpaceId;
-  get db(): EchoDatabase;
-
-  // TODO(dmaretskyi): Align with echo api: queues.get(id).append(items);
-  get queues(): QueuesAPI;
-}
-
-// TODO(wittjosiah): Queues are incompatible.
-const __assertFunctionSpaceIsCompatibleWithTheClientSpace = () => {
-  // const _: SpaceAPI = {} as Space;
+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 `Function.Function` object's metadata under the
+     *   `FUNCTIONS_META_KEY` and retrieved with `getUserFunctionIdInMetadata`.
+     */
+    deployedFunctionId?: string;
+  };
 };
 
-export type FunctionDefinition<T = {}, O = any> = {
+export type FunctionProps<T, O> = {
+  key: string;
   name: string;
   description?: string;
   inputSchema: Schema.Schema<T, any>;
@@ -95,14 +97,10 @@ export type FunctionDefinition<T = {}, O = any> = {
   handler: FunctionHandler<T, O>;
 };
 
-// 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: FunctionProps<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 +108,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,
+  } satisfies FunctionDefinition.Any;
+};
+
+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);
+  },
+};
+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>): 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),
+  });
+  if (functionDef.meta?.deployedFunctionId) {
+    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: () => {},
+    meta: {
+      deployedFunctionId: getUserFunctionIdInMetadata(Obj.getMeta(functionObj)),
+    },
   };
 };

package/src/index.ts

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

package/src/services/credentials.ts

@@ -2,9 +2,19 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Context, Effect } 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 { DatabaseService } from '@dxos/echo-db';
+import { AccessToken } from '@dxos/types';
+
+export type CredentialQuery = {
   service?: string;
 };
 
@@ -17,7 +27,7 @@ export type ServiceCredential = {
   apiKey?: string;
 };
 
-export class CredentialsService extends Context.Tag('CredentialsService')<
+export class CredentialsService extends Context.Tag('@dxos/functions/CredentialsService')<
   CredentialsService,
   {
     /**
@@ -37,6 +47,65 @@ export class CredentialsService extends Context.Tag('CredentialsService')<
       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(AccessToken.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> {
@@ -56,6 +125,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);
+    }),
+  );