@dxos/functions 0.8.4-main.67995b8 → 0.8.4-main.6fa680abb7

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';
 
@@ -14,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'),
@@ -43,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: 'org.dxos.type.compute-event', version: '0.1.0' }));
 
 /**
  * Logs event for the compute workflows.
@@ -66,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,
       };

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

@@ -0,0 +1,37 @@
+//
+// Copyright 2025 DXOS.org
+//
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import type { FunctionNotFoundError } from '../errors';
+import { type FunctionDefinition, type InvocationServices } from '../sdk';
+
+export class FunctionInvocationService extends Context.Tag('@dxos/functions/FunctionInvocationService')<
+  FunctionInvocationService,
+  {
+    invokeFunction<I, O>(
+      functionDef: FunctionDefinition<I, O, any>,
+      input: I,
+    ): Effect.Effect<O, never, InvocationServices>;
+
+    resolveFunction(key: string): Effect.Effect<FunctionDefinition.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: FunctionDefinition<I, O, any>,
+    input: I,
+  ): Effect.Effect<O, never, FunctionInvocationService | InvocationServices> =>
+    Effect.serviceFunctionEffect(FunctionInvocationService, (service) => service.invokeFunction)(functionDef, input);
+
+  static resolveFunction = (
+    key: string,
+  ): Effect.Effect<FunctionDefinition.Any, FunctionNotFoundError, FunctionInvocationService> =>
+    Effect.serviceFunctionEffect(FunctionInvocationService, (service) => service.resolveFunction)(key);
+}

package/src/services/index.ts

@@ -2,11 +2,10 @@
 // Copyright 2025 DXOS.org
 //
 
-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 './remote-function-execution-service';
-export * from './local-function-execution';
+export { createEventLogger, createDefectLogger } from './event-logger';
+export * from './function-invocation-service';
+export * from './queues';
+export * from './tracing';

package/src/services/queues.ts

@@ -2,9 +2,13 @@
 // 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 { Entity } from '@dxos/echo';
 import type { Queue, QueueAPI, QueueFactory } from '@dxos/echo-db';
+import type { DXN, QueueSubspaceTag } from '@dxos/keys';
 
 /**
  * Gives access to all queues.
@@ -21,30 +25,48 @@ export class QueueService extends Context.Tag('@dxos/functions/QueueService')<
      * The queue that is used to store the context of the current research.
      * @deprecated Use `ContextQueueService` instead.
      */
-    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): Context.Tag.Service<QueueService> => {
+  static make = (queues: QueueFactory, queue?: Queue): Context.Tag.Service<QueueService> => {
     return {
       queues,
-      contextQueue,
+      queue,
     };
   };
 
-  static makeLayer = (queues: QueueFactory, contextQueue?: Queue): Layer.Layer<QueueService> =>
-    Layer.succeed(QueueService, QueueService.make(queues, contextQueue));
+  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));
 }
 
 /**
@@ -53,6 +75,8 @@ export class QueueService extends Context.Tag('@dxos/functions/QueueService')<
 export class ContextQueueService extends Context.Tag('@dxos/functions/ContextQueueService')<
   ContextQueueService,
   {
-    readonly contextQueue: Queue;
+    readonly queue: Queue;
   }
->() {}
+>() {
+  static layer = (queue: Queue) => Layer.succeed(ContextQueueService, { queue });
+}

package/src/services/tracing.ts

@@ -2,11 +2,16 @@
 // 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 { AgentStatus } from '@dxos/ai';
-import { Obj } from '@dxos/echo';
-import type { AnyEchoObject } from '@dxos/echo-schema';
+import { type DXN, Obj } from '@dxos/echo';
+import { ObjectId } from '@dxos/keys';
+import { Message } from '@dxos/types';
+
+import type { Trigger } from '../types';
 
 /**
  * Provides a way for compute primitives (functions, workflows, tools)
@@ -15,30 +20,148 @@ import type { AnyEchoObject } from '@dxos/echo-schema';
 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.Unknown, traceContext: TracingService.TraceContext) => void;
+
+    traceInvocationStart({
+      payload,
+      target,
+    }: {
+      payload: TracingService.FunctionInvocationPayload;
+      target?: DXN;
+    }): Effect.Effect<TracingService.InvocationTraceData>;
+
+    traceInvocationEnd({
+      trace,
+      exception,
+    }: {
+      trace: TracingService.InvocationTraceData;
+      exception?: any;
+    }): Effect.Effect<void>;
   }
 >() {
-  static noop: Context.Tag.Service<TracingService> = { write: () => {} };
+  static noop: Context.Tag.Service<TracingService> = {
+    getTraceContext: () => ({}),
+    write: () => {},
+    traceInvocationStart: () =>
+      Effect.sync(() => ({ invocationId: ObjectId.random(), invocationTraceQueue: undefined })),
+    traceInvocationEnd: () => Effect.sync(() => {}),
+  };
 
-  static layerNoop = Layer.succeed(TracingService, TracingService.noop);
+  static layerNoop: Layer.Layer<TracingService> = Layer.succeed(TracingService, TracingService.noop);
 
-  static console: Context.Tag.Service<TracingService> = {
-    write: (event) => {
-      // eslint-disable-next-line no-console
-      console.log(event);
-    },
-  };
+  /**
+   * 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, context) => tracing.write(event, context),
+          getTraceContext: () => context,
+          traceInvocationStart: () => Effect.die('Tracing invocation inside another invocation is not supported.'),
+          traceInvocationEnd: () => Effect.die('Tracing invocation inside another invocation is not supported.'),
+        };
+      }),
+    );
+
+  /**
+   * Create sublayer to trace an invocation.
+   * @param data
+   * @returns
+   */
+  static layerInvocation = (data: TracingService.InvocationTraceData) =>
+    TracingService.layerSubframe((context) => ({
+      ...context,
+      currentInvocation: data,
+    }));
 
   /**
    * Emit the current human-readable execution status.
    */
-  static emitStatus: (data: Obj.MakeProps<typeof AgentStatus>) => Effect.Effect<unknown, never, void> =
-    Effect.fnUntraced(function* (data) {
-      const tracing = yield* TracingService;
-      tracing.write(Obj.make(AgentStatus, data));
-    });
+  static emitStatus: (
+    data: Omit<Obj.MakeProps<typeof AgentStatus>, 'created'>,
+  ) => 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,
+        created: new Date().toISOString(),
+        ...data,
+      }),
+      tracing.getTraceContext(),
+    );
+  });
+
+  static emitConverationMessage: (
+    data: Obj.MakeProps<typeof Message.Message>,
+  ) => Effect.Effect<void, never, TracingService> = Effect.fnUntraced(function* (data) {
+    const tracing = yield* TracingService;
+    tracing.write(
+      Obj.make(Message.Message, {
+        parentMessage: tracing.getTraceContext().parentMessage,
+        ...data,
+        properties: {
+          [MESSAGE_PROPERTY_TOOL_CALL_ID]: tracing.getTraceContext().toolCallId,
+          ...data.properties,
+        },
+      }),
+      tracing.getTraceContext(),
+    );
+  });
 }
+
+export namespace TracingService {
+  export interface TraceContext {
+    currentInvocation?: InvocationTraceData;
+
+    /**
+     * 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;
+  }
+
+  /**
+   * Trace data for a function/trigger invocation.
+   */
+  export interface InvocationTraceData {
+    invocationId: ObjectId;
+    invocationTraceQueue?: DXN.String;
+  }
+
+  /**
+   * Payload for a function/trigger invocation.
+   */
+  export interface FunctionInvocationPayload {
+    data?: any;
+    inputNodeId?: string;
+    trigger?: {
+      id: string;
+      kind: Trigger.Kind;
+    };
+  }
+}
+
+/**
+ * Goes into {@link Message['properties']}
+ */
+export const MESSAGE_PROPERTY_TOOL_CALL_ID = 'toolCallId' as const;

package/src/types/Function.ts

@@ -0,0 +1,83 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Annotation, JsonSchema, Obj, Ref, Type } from '@dxos/echo';
+import { SystemTypeAnnotation } from '@dxos/echo/internal';
+
+import { Script } from './Script';
+
+/**
+ * Function deployment.
+ */
+export const Function = 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',
+  }),
+
+  name: Schema.NonEmptyString,
+  version: Schema.String,
+
+  description: Schema.optional(Schema.String),
+
+  /**
+   * ISO date string of the last deployment.
+   */
+  updated: Schema.optional(Schema.String),
+
+  // Reference to a source script if it exists within ECHO.
+  // TODO(burdon): Don't ref ScriptType directly (core).
+  source: Schema.optional(Ref.Ref(Script)),
+
+  inputSchema: Schema.optional(JsonSchema.JsonSchema),
+  outputSchema: Schema.optional(JsonSchema.JsonSchema),
+
+  /**
+   * List of required services.
+   * Match the Context.Tag keys of the FunctionServices variants.
+   */
+  services: Schema.optional(Schema.Array(Schema.String)),
+
+  // Local binding to a function name.
+  binding: Schema.optional(Schema.String),
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.function',
+    version: '0.1.0',
+  }),
+  Annotation.LabelAnnotation.set(['name']),
+  Annotation.IconAnnotation.set({ icon: 'ph--function--regular', hue: 'blue' }),
+  SystemTypeAnnotation.set(true),
+);
+
+export interface Function extends Schema.Schema.Type<typeof Function> {}
+
+export const make = (props: Obj.MakeProps<typeof Function>) => Obj.make(Function, props);
+
+/**
+ * Copies properties from source to target.
+ * @param target - Target object to copy properties to.
+ * @param source - Source object to copy properties from.
+ */
+export const setFrom = (target: Function, source: Function) => {
+  Obj.change(target, (t) => {
+    t.key = source.key ?? target.key;
+    t.name = source.name ?? target.name;
+    t.version = source.version;
+    t.description = source.description;
+    t.updated = source.updated;
+    // TODO(dmaretskyi): A workaround for an ECHO bug.
+    t.inputSchema = source.inputSchema ? JSON.parse(JSON.stringify(source.inputSchema)) : undefined;
+    t.outputSchema = source.outputSchema ? JSON.parse(JSON.stringify(source.outputSchema)) : undefined;
+    Obj.getMeta(t).keys = JSON.parse(JSON.stringify(Obj.getMeta(source).keys));
+  });
+};

package/src/types/Script.ts

@@ -0,0 +1,34 @@
+//
+// 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']),
+);
+
+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(source)) });

package/src/types/Trigger.ts

@@ -0,0 +1,154 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { Annotation, Obj, QueryAST, Ref, Type } from '@dxos/echo';
+import { OptionsAnnotationId, SystemTypeAnnotation } from '@dxos/echo/internal';
+import { DXN } from '@dxos/keys';
+import { Expando } from '@dxos/schema';
+
+/**
+ * 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>;
+
+// 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): Change to a reference.
+  queue: DXN.Schema,
+});
+export type QueueSpec = Schema.Schema.Type<typeof QueueSpec>;
+
+/**
+ * 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>;
+
+/**
+ * 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>;
+
+/**
+ * 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>;
+
+/**
+ * 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(Expando.Expando).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 queue triggers, this will process queue items in parallel.',
+    }),
+  ),
+
+  /**
+   * Passed as the input data to the function.
+   * Must match the function's input schema.
+   *
+   * @example
+   * {
+   *   item: '{{$.trigger.event}}',
+   *   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);