@dxos/functions 0.8.4-main.84f28bd → 0.8.4-main.937b3ca

package/src/services/event-logger.ts

@@ -2,53 +2,90 @@
 // 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 { Obj, 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;
-    };
+import { TracingService } from './tracing';
+
+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 class EventLogger extends Context.Tag('EventLogger')<
-  EventLogger,
-  { readonly log: (event: ComputeEvent) => void; readonly nodeId: string | undefined }
+export const ComputeEvent = Schema.Struct({
+  payload: ComputeEventPayload,
+}).pipe(Type.object({ typename: 'dxos.org/type/ComputeEvent', version: '0.1.0' }));
+
+/**
+ * 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,
   };
+
+  /**
+   * Implements ComputeEventLogger using TracingService.
+   */
+  static layerFromTracing = Layer.effect(
+    ComputeEventLogger,
+    Effect.gen(function* () {
+      const tracing = yield* TracingService;
+      return {
+        log: (event: ComputeEventPayload) => {
+          tracing.write(Obj.make(ComputeEvent, { payload: event }), tracing.getTraceContext());
+        },
+        nodeId: undefined,
+      };
+    }),
+  );
 }
 
 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 +104,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 +119,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,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,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 * from './tracing';

package/src/services/queues.ts

@@ -2,11 +2,18 @@
 // 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';
 
-export class QueueService extends Context.Tag('QueueService')<
+/**
+ * Gives access to all queues.
+ */
+export class QueueService extends Context.Tag('@dxos/functions/QueueService')<
   QueueService,
   {
     /**
@@ -16,27 +23,60 @@ 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.
+ */
+export class ContextQueueService extends Context.Tag('@dxos/functions/ContextQueueService')<
+  ContextQueueService,
+  {
+    readonly queue: Queue;
+  }
+>() {
+  static layer = (queue: Queue) => Layer.succeed(ContextQueueService, { queue });
 }

package/src/services/tracing.ts

@@ -2,26 +2,166 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Context } from 'effect';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
 
-import type { AnyEchoObject } from '@dxos/echo-schema';
+import { AgentStatus } from '@dxos/ai';
+import { type DXN, Obj } from '@dxos/echo';
+import { ObjectId } from '@dxos/keys';
+import { Message } from '@dxos/types';
 
-export class TracingService extends Context.Tag('TracingService')<
+import type { Trigger } from '../types';
+
+/**
+ * Provides a way for compute primitives (functions, workflows, tools)
+ * to emit an execution trace as a series of structured ECHO objects.
+ */
+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 console: Context.Tag.Service<TracingService> = {
-    write: (event) => {
-      // eslint-disable-next-line no-console
-      console.log(event);
-    },
+  static noop: Context.Tag.Service<TracingService> = {
+    getTraceContext: () => ({}),
+    write: () => {},
+    traceInvocationStart: () =>
+      Effect.sync(() => ({ invocationId: ObjectId.random(), invocationTraceQueue: undefined })),
+    traceInvocationEnd: () => Effect.sync(() => {}),
   };
+
+  static layerNoop: Layer.Layer<TracingService> = Layer.succeed(TracingService, TracingService.noop);
+
+  /**
+   * 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: 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,82 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Annotation, JsonSchema, Obj, 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(Type.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: 'dxos.org/type/Function',
+    version: '0.1.0',
+  }),
+  Annotation.LabelAnnotation.set(['name']),
+  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: Type.Ref(Text.Text).pipe(FormInputAnnotation.set(false)),
+}).pipe(
+  Type.object({
+    typename: 'dxos.org/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)) });