@dxos/functions 0.8.4-main.f9ba587 → 0.8.4-main.fcfe5033a5

package/src/services/event-logger.ts

@@ -2,53 +2,74 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Effect, Context } 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 { 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;
-    };
+export const ComputeEventPayload = Schema.Union(
+  Schema.Struct({
+    type: Schema.Literal('begin-compute'),
+    nodeId: Schema.String,
+    /**
+     * Names of the inputs begin computed.
+     */
+    inputs: Schema.Array(Schema.String),
+  }),
+  Schema.Struct({
+    type: Schema.Literal('end-compute'),
+    nodeId: Schema.String,
+    /**
+     * Names of the outputs computed.
+     */
+    outputs: Schema.Array(Schema.String),
+  }),
+  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 const ComputeEvent = Schema.Struct({
+  payload: ComputeEventPayload,
+}).pipe(Type.object({ typename: 'org.dxos.type.computeEvent', version: '0.1.0' }));
 
-export class EventLogger extends Context.Tag('EventLogger')<
-  EventLogger,
-  { readonly log: (event: ComputeEvent) => void; readonly nodeId: string | undefined }
+/**
+ * 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,
   };
+
+  static layerNoop: Layer.Layer<ComputeEventLogger> = Layer.succeed(ComputeEventLogger, ComputeEventLogger.noop);
 }
 
 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 +88,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 +103,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/function-invocation-service.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2025 DXOS.org
+//
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { Operation } from '@dxos/operation';
+
+import type { FunctionNotFoundError } from '../errors';
+
+export class FunctionInvocationService extends Context.Tag('@dxos/functions/FunctionInvocationService')<
+  FunctionInvocationService,
+  {
+    invokeFunction<I, O>(functionDef: Operation.Definition<I, O, any>, input: I): Effect.Effect<O>;
+
+    resolveFunction(key: string): Effect.Effect<Operation.Definition.Any, FunctionNotFoundError>;
+  }
+>() {
+  static layerNotAvailable = Layer.succeed(FunctionInvocationService, {
+    invokeFunction: () => Effect.die('FunctionInvocationService is not avaialble.'),
+    resolveFunction: () => Effect.die('FunctionInvocationService is not available.'),
+  });
+
+  static invokeFunction = <I, O>(
+    functionDef: Operation.Definition<I, O, any>,
+    input: I,
+  ): Effect.Effect<O, never, FunctionInvocationService> =>
+    Effect.serviceFunctionEffect(FunctionInvocationService, (service) => service.invokeFunction)(functionDef, input);
+
+  static resolveFunction = (
+    key: string,
+  ): Effect.Effect<Operation.Definition.Any, FunctionNotFoundError, FunctionInvocationService> =>
+    Effect.serviceFunctionEffect(FunctionInvocationService, (service) => service.resolveFunction)(key);
+}

package/src/services/index.ts

@@ -2,12 +2,10 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './ai';
-export * from './database';
-export * from './queues';
-export * from './service-container';
 export * from './credentials';
-export * from './tracing';
+export { ConfiguredCredentialsService, type ServiceCredential } from './credentials';
 export * from './event-logger';
-export * from './function-call-service';
-export * from './tool-resolver';
+export { createEventLogger, createDefectLogger } from './event-logger';
+export * from './function-invocation-service';
+export * from './queues';
+export { MESSAGE_PROPERTY_TOOL_CALL_ID } from './tracing';

package/src/services/queues.ts

@@ -2,11 +2,19 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Context, Layer } from 'effect';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
 
-import type { Queue, QueueAPI, QueueFactory } from '@dxos/echo-db';
+import { type Entity } from '@dxos/echo';
+import { createFeedServiceLayer, type Queue, type QueueAPI, type QueueFactory } from '@dxos/echo-db';
+import type { DXN, QueueSubspaceTag } from '@dxos/keys';
 
-export class QueueService extends Context.Tag('QueueService')<
+/**
+ * Gives access to all queues.
+ * @deprecated Use Feed.FeedService instead.
+ */
+export class QueueService extends Context.Tag('@dxos/functions/QueueService')<
   QueueService,
   {
     /**
@@ -16,27 +24,68 @@ export class QueueService extends Context.Tag('QueueService')<
 
     /**
      * 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, {
     queues: {
-      get(dxn) {
+      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 Entity.Unknown = Entity.Unknown>(
+    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 Entity.Unknown = Entity.Unknown>(options?: {
+    subspaceTag?: QueueSubspaceTag;
+  }): Effect.Effect<Queue<T>, never, QueueService> =>
+    QueueService.pipe(Effect.map(({ queues }) => queues.create<T>(options)));
+
+  static append = <T extends Entity.Unknown = Entity.Unknown>(queue: Queue<T>, objects: T[]): Effect.Effect<void> =>
+    Effect.promise(() => queue.append(objects));
+}
+
+/**
+ * Gives access to a specific queue passed as a context.
+ * @deprecated Use Feed.FeedService instead.
+ */
+export class ContextQueueService extends Context.Tag('@dxos/functions/ContextQueueService')<
+  ContextQueueService,
+  {
+    readonly queue: Queue;
+  }
+>() {
+  static layer = (queue: Queue) => Layer.succeed(ContextQueueService, { queue });
 }
+
+export const feedServiceFromQueueServiceLayer = Layer.unwrapEffect(
+  Effect.gen(function* () {
+    const { queues } = yield* QueueService;
+    return createFeedServiceLayer(queues);
+  }),
+);

package/src/services/tracing.ts

@@ -2,26 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Context } from 'effect';
-
-import type { AnyEchoObject } from '@dxos/echo-schema';
-
-export class TracingService extends Context.Tag('TracingService')<
-  TracingService,
-  {
-    /**
-     * Write an event to the tracing queue.
-     * @param event - The event to write. Must be an a typed object.
-     */
-    write(event: AnyEchoObject): void;
-  }
->() {
-  static noop: Context.Tag.Service<TracingService> = { write: () => {} };
-
-  static console: Context.Tag.Service<TracingService> = {
-    write: (event) => {
-      // eslint-disable-next-line no-console
-      console.log(event);
-    },
-  };
-}
+/**
+ * Goes into {@link Message['properties']}
+ */
+export const MESSAGE_PROPERTY_TOOL_CALL_ID = 'toolCallId' as const;

package/src/types/Script.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Annotation, Obj, Ref, Type } from '@dxos/echo';
+import { FormInputAnnotation } from '@dxos/echo/internal';
+import { Text } from '@dxos/schema';
+
+/**
+ * Source script.
+ */
+export const Script = Schema.Struct({
+  name: Schema.String.pipe(Schema.optional),
+  description: Schema.String.pipe(Schema.optional),
+  // TODO(burdon): Change to hash of deployed content.
+  // Whether source has changed since last deploy.
+  changed: Schema.Boolean.pipe(FormInputAnnotation.set(false), Schema.optional),
+  source: Ref.Ref(Text.Text).pipe(FormInputAnnotation.set(false)),
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.script',
+    version: '0.1.0',
+  }),
+  Annotation.LabelAnnotation.set(['name']),
+  Annotation.IconAnnotation.set({
+    icon: 'ph--code--regular',
+    hue: 'sky',
+  }),
+);
+
+export interface Script extends Schema.Schema.Type<typeof Script> {}
+
+type Props = Omit<Obj.MakeProps<typeof Script>, 'source'> & { source?: string };
+
+export const make = ({ source = '', ...props }: Props = {}): Script =>
+  Obj.make(Script, { ...props, source: Ref.make(Text.make({ content: source })) });

package/src/types/Trigger.ts

@@ -0,0 +1,207 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { Annotation, Feed, Obj, QueryAST, Ref, Type, type Query } from '@dxos/echo';
+import { OptionsAnnotationId, SystemTypeAnnotation } from '@dxos/echo/internal';
+import { failedInvariant } from '@dxos/invariant';
+import { DXN } from '@dxos/keys';
+
+/**
+ * Type discriminator for TriggerType.
+ * Every spec has a type field of type TriggerKind that we can use to understand which type we're working with.
+ * https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions
+ */
+export const Kinds = ['email', 'queue', 'subscription', 'timer', 'webhook'] as const;
+export type Kind = (typeof Kinds)[number];
+
+const kindLiteralAnnotations = { title: 'Kind' };
+
+export const EmailSpec = Schema.Struct({
+  kind: Schema.Literal('email').annotations(kindLiteralAnnotations),
+});
+export type EmailSpec = Schema.Schema.Type<typeof EmailSpec>;
+
+/**
+ * Construct an Email trigger spec.
+ */
+export const specEmail = (): EmailSpec => ({ kind: 'email' });
+
+// TODO(burdon): Change to Feed.
+// TODO(wittjosiah): Remove. Migrate to Subscription triggers once EDGE supports them for feed queries.
+export const QueueSpec = Schema.Struct({
+  kind: Schema.Literal('queue').annotations(kindLiteralAnnotations),
+
+  // TODO(dmaretskyi): Rename to `feed` and change to a reference.
+  queue: DXN.Schema,
+});
+export type QueueSpec = Schema.Schema.Type<typeof QueueSpec>;
+
+/**
+ * Construct a Queue trigger spec from a queue DXN string.
+ */
+export const specQueue = (queueDxn: string): QueueSpec => ({
+  kind: 'queue',
+  queue: queueDxn,
+});
+
+/**
+ * Construct a Queue trigger spec from a Feed object.
+ */
+export const specFeed = (feed: Feed.Feed): QueueSpec =>
+  specQueue(Feed.getQueueDxn(feed)?.toString() ?? failedInvariant(new Error('Could not extract DXN from feed')));
+
+/**
+ * Subscription.
+ */
+export const SubscriptionSpec = Schema.Struct({
+  kind: Schema.Literal('subscription').annotations(kindLiteralAnnotations),
+  query: Schema.Struct({
+    raw: Schema.optional(Schema.String.annotations({ title: 'Query' })),
+    ast: QueryAST.Query,
+  }),
+  options: Schema.optional(
+    Schema.Struct({
+      // Watch changes to object (not just creation).
+      deep: Schema.optional(Schema.Boolean.annotations({ title: 'Nested' })),
+      // Debounce changes (delay in ms).
+      delay: Schema.optional(Schema.Number.annotations({ title: 'Delay' })),
+    }).annotations({ title: 'Options' }),
+  ),
+});
+export type SubscriptionSpec = Schema.Schema.Type<typeof SubscriptionSpec>;
+
+/**
+ * Construct a Subscription trigger spec from a Query object.
+ */
+export const specSubscription = (
+  query: Query.Query<any>,
+  options?: { deep?: boolean; delay?: number },
+): SubscriptionSpec => ({
+  kind: 'subscription',
+  query: {
+    ast: query.ast,
+  },
+  options: options
+    ? {
+        deep: options.deep,
+        delay: options.delay,
+      }
+    : undefined,
+});
+
+/**
+ * Cron timer.
+ */
+export const TimerSpec = Schema.Struct({
+  kind: Schema.Literal('timer').annotations(kindLiteralAnnotations),
+  cron: Schema.String.annotations({
+    title: 'Cron',
+    [SchemaAST.ExamplesAnnotationId]: ['0 0 * * *'],
+  }),
+});
+export type TimerSpec = Schema.Schema.Type<typeof TimerSpec>;
+
+/**
+ * Construct a Timer trigger spec from a cron string.
+ */
+export const specTimer = (cron: string): TimerSpec => ({ kind: 'timer', cron });
+
+/**
+ * Webhook.
+ */
+export const WebhookSpec = Schema.Struct({
+  kind: Schema.Literal('webhook').annotations(kindLiteralAnnotations),
+  method: Schema.optional(
+    Schema.String.annotations({
+      title: 'Method',
+      [OptionsAnnotationId]: ['GET', 'POST'],
+    }),
+  ),
+  port: Schema.optional(
+    Schema.Number.annotations({
+      title: 'Port',
+    }),
+  ),
+});
+export type WebhookSpec = Schema.Schema.Type<typeof WebhookSpec>;
+
+/**
+ * Construct a Webhook trigger spec from a method and port.
+ */
+export const specWebhook = (opts?: { method?: string; port?: number }): WebhookSpec => ({
+  kind: 'webhook',
+  method: opts?.method,
+  port: opts?.port,
+});
+
+/**
+ * Trigger schema.
+ */
+export const Spec = Schema.Union(EmailSpec, QueueSpec, SubscriptionSpec, TimerSpec, WebhookSpec).annotations({
+  title: 'Trigger',
+});
+export type Spec = Schema.Schema.Type<typeof Spec>;
+
+/**
+ * Function trigger.
+ * Function is invoked with the `payload` passed as input data.
+ * The event that triggers the function is available in the function context.
+ */
+const TriggerSchema = Schema.Struct({
+  /**
+   * Function or workflow to invoke.
+   */
+  // TODO(dmaretskyi): Can be a Ref(FunctionType) or Ref(ComputeGraphType).
+  function: Schema.optional(Ref.Ref(Obj.Unknown).annotations({ title: 'Function' })),
+
+  /**
+   * Only used for workflowSchema.
+   * Specifies the input node in the circuit.
+   * @deprecated Remove and enforce a single input node in all compute graphSchema.
+   */
+  inputNodeId: Schema.optional(Schema.String.annotations({ title: 'Input Node ID' })),
+
+  // TODO(burdon): NO BOOLEAN PROPERTIES (enabld/disabled/paused, etc.)
+  //  Need lint rule; or agent rule to require PR review for "boolean" key word.
+  enabled: Schema.optional(Schema.Boolean.annotations({ title: 'Enabled' })),
+
+  spec: Schema.optional(Spec),
+
+  concurrency: Schema.optional(
+    Schema.Number.annotations({
+      title: 'Concurrency',
+      default: 1,
+      description:
+        'Maximum number of concurrent invocations of the trigger. For Feed triggers, this will process Feed items in parallel.',
+    }),
+  ),
+
+  /**
+   * Passed as the input data to the function.
+   * Must match the function's input schema.
+   *
+   * @example
+   * {
+   *   item: '{{event.item}}',
+   *   instructions: 'Summarize and perform entity-extraction'
+   *   mailbox: { '/': 'dxn:echo:AAA:ZZZ' }
+   * }
+   */
+  input: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Any })),
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.trigger',
+    version: '0.1.0',
+  }),
+  Annotation.IconAnnotation.set({ icon: 'ph--lightning--regular', hue: 'yellow' }),
+  SystemTypeAnnotation.set(true),
+);
+
+export interface Trigger extends Schema.Schema.Type<typeof TriggerSchema> {}
+export const Trigger: Type.Obj<Trigger> = TriggerSchema as any;
+
+export const make = (props: Obj.MakeProps<typeof Trigger>) => Obj.make(Trigger, props);

package/src/types/TriggerEvent.ts

@@ -0,0 +1,62 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { DXN, Obj, Ref } from '@dxos/echo';
+
+// TODO(wittjosiah): Review this type.
+//   - Should be discriminated union.
+//   - Should be more consistent (e.g. subject vs item).
+//   - Should re-use schemas if possible.
+
+// TODO(burdon): Reuse trigger schema from @dxos/functions (TriggerType).
+export const EmailEvent = Schema.Struct({
+  from: Schema.String,
+  to: Schema.String,
+  subject: Schema.String,
+  created: Schema.String,
+  body: Schema.String,
+});
+export type EmailEvent = Schema.Schema.Type<typeof EmailEvent>;
+
+export const QueueEvent = Schema.Struct({
+  queue: DXN.Schema,
+  item: Schema.Any,
+  cursor: Schema.String,
+});
+export type QueueEvent = Schema.Schema.Type<typeof QueueEvent>;
+
+export const SubscriptionEvent = Schema.Struct({
+  /**
+   * Type of the mutation.
+   */
+  // TODO(dmaretskyi): Specify enum.
+  type: Schema.String,
+
+  /**
+   * Reference to the object that was changed or created.
+   */
+  subject: Ref.Ref(Obj.Unknown),
+
+  /**
+   * @deprecated
+   */
+  changedObjectId: Schema.optional(Schema.String),
+});
+export type SubscriptionEvent = Schema.Schema.Type<typeof SubscriptionEvent>;
+
+export const TimerEvent = Schema.Struct({ tick: Schema.Number });
+export type TimerEvent = Schema.Schema.Type<typeof TimerEvent>;
+
+export const WebhookEvent = Schema.Struct({
+  url: Schema.String,
+  method: Schema.Literal('GET', 'POST'),
+  headers: Schema.Record({ key: Schema.String, value: Schema.String }),
+  bodyText: Schema.String,
+});
+export type WebhookEvent = Schema.Schema.Type<typeof WebhookEvent>;
+
+export const TriggerEvent = Schema.Union(EmailEvent, QueueEvent, SubscriptionEvent, TimerEvent, WebhookEvent);
+export type TriggerEvent = Schema.Schema.Type<typeof TriggerEvent>;

package/src/types/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * as Script from './Script';
+export * as Trigger from './Trigger';
+export * as TriggerEvent from './TriggerEvent';
+export * from './url';

package/src/types/url.ts

@@ -0,0 +1,32 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Obj } from '@dxos/echo';
+
+// TODO: use URL scheme for source?
+export const FUNCTIONS_META_KEY = 'org.dxos.service.function';
+
+export const FUNCTIONS_PRESET_META_KEY = 'org.dxos.service.function-preset';
+
+/**
+ * NOTE: functionId is backend ID, not ECHO object id.
+ */
+export const getUserFunctionIdInMetadata = (meta: Obj.ReadonlyMeta) => {
+  return meta.keys.find((key) => key.source === FUNCTIONS_META_KEY)?.id;
+};
+
+/**
+ * NOTE: functionId is backend ID, not ECHO object id.
+ * Must be called inside Obj.changeMeta() since it mutates the meta.
+ */
+export const setUserFunctionIdInMetadata = (meta: Obj.Meta, functionId: string) => {
+  const key = meta.keys.find((key) => key.source === FUNCTIONS_META_KEY);
+  if (key) {
+    if (key.id !== functionId) {
+      throw new Error('Metadata mismatch');
+    }
+  } else {
+    meta.keys.push({ source: FUNCTIONS_META_KEY, id: functionId });
+  }
+};