@dxos/compute 0.8.4-main.fcfe5033a5 → 0.8.4-staging.60fe92afc8

package/src/Trace.ts

@@ -0,0 +1,363 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+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 { DXN, Annotation, Obj, Type } from '@dxos/echo';
+import { log } from '@dxos/log';
+
+/**
+ * Writes ephemeral or persistent events to the trace.
+ * Exposed to processes and operations to record events to the trace.
+ */
+export interface TraceWriter {
+  write<T>(eventType: EventType<T>, payload: NoInfer<T>): void;
+}
+
+/**
+ * Service that writes events to the trace.
+ * Exposed to processes and operations to record events to the trace.
+ */
+export class TraceService extends Context.Tag('@dxos/functions/TraceService')<TraceService, TraceWriter>() {}
+
+/**
+ * Writes an event to the trace.
+ */
+export function write<T>(eventType: EventType<T>, payload: NoInfer<T>): Effect.Effect<void, never, TraceService> {
+  return Effect.gen(function* () {
+    log('trace write', { key: eventType.key, isEphemeral: eventType.isEphemeral });
+    const writer = yield* TraceService;
+    writer.write(eventType, payload);
+  });
+}
+
+/**
+ * Defines an event type for the trace.
+ */
+export interface EventType<T> {
+  readonly key: string;
+  readonly schema: Schema.Schema<T, any>;
+  readonly isEphemeral: boolean;
+}
+
+export const EventType = <T>(
+  key: string,
+  opts: { schema: Schema.Schema<T, any>; isEphemeral: boolean },
+): EventType<T> => {
+  return {
+    key,
+    schema: opts.schema,
+    isEphemeral: opts.isEphemeral,
+  };
+};
+
+/**
+ * Extracts the payload type from an event type.
+ */
+export type PayloadType<E extends EventType<any>> = E extends EventType<infer T> ? T : never;
+
+export const Event = Schema.Struct({
+  timestamp: Schema.Number,
+  type: Schema.String,
+  data: Schema.Unknown, // Type-specific payload;
+});
+export type Event = Schema.Schema.Type<typeof Event>;
+/**
+ * Checks if an event is of a given type.
+ */
+export const isOfType = <T, E extends Event>(eventType: EventType<T>, event: E): event is E & { data: T } => {
+  return event.type === eventType.key;
+};
+
+/**
+ * Extensible name informing which runtime executed the code that produced the event.
+ */
+export const RuntimeName = Schema.String.pipe(Schema.brand('@dxos/compute/Trace/RuntimeName'));
+export type RuntimeName = Schema.Schema.Type<typeof RuntimeName>;
+
+/**
+ * Common runtime names.
+ */
+export const CommonRuntimeName = {
+  /**
+   * Web app / CLI / Desktop app / Mobile app.
+   */
+  local: RuntimeName.make('local'),
+  edgeIntrinsic: RuntimeName.make('edge-intrinsic'),
+  edgeWorkerLoader: RuntimeName.make('edge-worker-loader'),
+  edgeWorkerForPlatforms: RuntimeName.make('edge-worker-for-platforms'),
+};
+
+/**
+ * Metadata on the context of a trace message.
+ */
+// TODO(dmaretskyi): Expand on this: conversation id, tool call id, etc.
+export const Meta = Schema.Struct({
+  pid: Schema.optional(Schema.String), // NOTE: Not Process.ID to avoid circular dependency.
+  parentPid: Schema.optional(Schema.String),
+  processName: Schema.optional(Schema.String),
+
+  /**
+   * Space the message was produced in.
+   * Stored as a string to avoid circular dependency on `@dxos/keys`.
+   */
+  space: Schema.optional(Schema.String),
+
+  /**
+   * ID of the conversation feed object if present.
+   */
+  conversationId: Schema.optional(Obj.ID),
+
+  /**
+   * ID of the trigger object if invocation resulted from a trigger.
+   */
+  triggerId: Schema.optional(Obj.ID),
+
+  /**
+   * ID of the tool call that created the current process.
+   */
+  toolCallId: Schema.optional(Schema.String),
+
+  /**
+   * Extensible name informing which runtime executed the code that produced the event.
+   */
+  runtimeName: Schema.optional(RuntimeName),
+});
+export type Meta = Schema.Schema.Type<typeof Meta>;
+/**
+ * Checks if a runtime is an edge runtime.
+ */
+export const isEdgeRuntime = (name: RuntimeName): boolean =>
+  name === CommonRuntimeName.edgeIntrinsic ||
+  name === CommonRuntimeName.edgeWorkerLoader ||
+  name === CommonRuntimeName.edgeWorkerForPlatforms;
+
+/**
+ * Envelope for a set of events.
+ */
+export const MessageData = Schema.Struct({
+  meta: Meta,
+
+  isEphemeral: Schema.Boolean,
+  events: Schema.Array(Event),
+});
+export type MessageData = Schema.Schema.Type<typeof MessageData>;
+export const Message = MessageData.pipe(
+  Annotation.IconAnnotation.set({ icon: 'ph--note--regular', hue: 'rose' }),
+  Annotation.HiddenAnnotation.set(true),
+  Type.makeObject(DXN.make('org.dxos.type.traceMessage', '0.1.0')),
+);
+export type Message = Type.InstanceType<typeof Message>;
+/**
+ * Flattened representation of a signle event in a trace message.
+ * Events are stored in batched messages for efficiency, but flat representation is more convenient for consumption.
+ */
+export interface FlatEvent extends Event {
+  readonly meta: Meta;
+  readonly isEphemeral: boolean;
+}
+
+/**
+ * Flattens a trace message into a list of flat events.
+ */
+export const flatten = (message: Message): FlatEvent[] => {
+  return message.events.map((event) => ({
+    ...event,
+    meta: message.meta,
+    isEphemeral: message.isEphemeral,
+  }));
+};
+
+/**
+ * Sink for complete trace messages.
+ */
+export interface Sink {
+  write(message: Message): void;
+}
+
+/**
+ * Sink for complete trace messages.
+ * The Process Manager forwards trace messages to it.
+ */
+// TODO(dmaretskyi): Consider moving sink to the Process Manager.
+export class TraceSink extends Context.Tag('@dxos/functions/TraceSink')<TraceSink, Sink>() {}
+
+export const noopWriter: TraceWriter = {
+  write: () => {},
+};
+
+export const writerLayerNoop: Layer.Layer<TraceService> = Layer.succeed(TraceService, noopWriter);
+
+export const noopSink: Sink = {
+  write: () => {},
+};
+
+export const layerNoop: Layer.Layer<TraceSink> = Layer.succeed(TraceSink, noopSink);
+
+export const layerConsole: Layer.Layer<TraceSink> = Layer.succeed(TraceSink, {
+  write: (message) => {
+    console.log(message);
+  },
+});
+
+/**
+ * Merge a set of sinks into a single sink.
+ *
+ * Each message is forwarded to every sink in order. Failures in one sink do not
+ * prevent downstream sinks from receiving the message.
+ */
+export const mergeSinks = (sinks: readonly Sink[]): Sink => {
+  if (sinks.length === 0) {
+    return noopSink;
+  }
+  // Intentionally no singleton fast path: the guarded wrapper is the
+  // contract of `mergeSinks`, so a throwing sink is always caught and
+  // logged regardless of how many sinks were passed in.
+  return {
+    write: (message) => {
+      for (const sink of sinks) {
+        try {
+          sink.write(message);
+        } catch (err) {
+          // Intentional: do not let one sink break the chain.
+          // eslint-disable-next-line no-console
+          console.error('[trace] sink.write threw', err);
+        }
+      }
+    },
+  };
+};
+
+/**
+ * Builds a {@link TraceService} layer that wraps each `write` into a fresh {@link Message}
+ * and forwards it to the provided {@link TraceSink}. Intended for tests and lightweight
+ * fixtures.
+ *
+ * Options:
+ *   - `meta`: stamped on every emitted message (defaults to `{}`).
+ *   - `clock`: timestamp source (defaults to {@link Date.now}). Pass a monotonic counter
+ *     in tests to make event ordering deterministic when many writes happen in the same
+ *     millisecond.
+ */
+export const testTraceService = (
+  opts: { meta?: Meta; clock?: () => number } = {},
+): Layer.Layer<TraceService, never, TraceSink> =>
+  Layer.effect(
+    TraceService,
+    Effect.gen(function* () {
+      const sink = yield* TraceSink;
+      const clock = opts.clock ?? Date.now;
+      return {
+        write: (event, data) => {
+          sink.write(
+            Obj.make(Message, {
+              meta: opts.meta ?? {},
+              isEphemeral: event.isEphemeral,
+              events: [{ type: event.key, timestamp: clock(), data }],
+            }),
+          );
+        },
+      };
+    }),
+  );
+
+//
+// Operation Trace Events
+//
+
+/**
+ * Outcome of an operation invocation.
+ */
+export type OperationOutcome = 'success' | 'failure';
+
+/**
+ * Operation invocation started.
+ */
+export const OperationStart = EventType('operation.start', {
+  schema: Schema.Struct({
+    /** Operation key. */
+    key: Schema.String,
+    /** Human-readable operation name. */
+    name: Schema.optional(Schema.String),
+    /** Phosphor icon identifier in `ph--<name>--<variant>` format. */
+    icon: Schema.optional(Schema.String),
+  }),
+  isEphemeral: false,
+});
+
+/**
+ * Operation invocation ended.
+ */
+export const OperationEnd = EventType('operation.end', {
+  schema: Schema.Struct({
+    /** Operation key. */
+    key: Schema.String,
+    /** Human-readable operation name. */
+    name: Schema.optional(Schema.String),
+    /** Phosphor icon identifier in `ph--<name>--<variant>` format. */
+    icon: Schema.optional(Schema.String),
+    /** Outcome of the operation. */
+    outcome: Schema.Literal('success', 'failure'),
+    /** Error message if the operation failed. */
+    error: Schema.optional(Schema.String),
+  }),
+  isEphemeral: false,
+});
+
+/**
+ * Operation input. Emitted as an ephemeral event alongside {@link OperationStart}
+ * so subscribers (such as the undo/redo history tracker) can observe the raw
+ * input payload without persisting it to long-lived sinks.
+ */
+export const OperationInput = EventType('operation.input', {
+  schema: Schema.Struct({
+    /** Operation key. */
+    key: Schema.String,
+    /** Human-readable operation name. */
+    name: Schema.optional(Schema.String),
+    /** Raw operation input. Shape determined by the operation definition. */
+    input: Schema.Unknown,
+  }),
+  isEphemeral: true,
+});
+
+/**
+ * Operation output. Emitted as an ephemeral event just before
+ * {@link OperationEnd} for successful invocations so subscribers (such as the
+ * undo/redo history tracker) can observe the raw output payload without
+ * persisting it to long-lived sinks.
+ */
+export const OperationOutput = EventType('operation.output', {
+  schema: Schema.Struct({
+    /** Operation key. */
+    key: Schema.String,
+    /** Human-readable operation name. */
+    name: Schema.optional(Schema.String),
+    /** Raw operation output. Shape determined by the operation definition. */
+    output: Schema.Unknown,
+  }),
+  isEphemeral: true,
+});
+
+/**
+ * Human-readable status update emitted by an agent or operation.
+ */
+export const StatusUpdate = EventType('status.update', {
+  schema: Schema.Struct({
+    /** Human-readable status message. */
+    message: Schema.String,
+  }),
+  isEphemeral: true,
+});
+
+/**
+ * Emit the current human-readable execution status to the trace.
+ */
+export const emitStatus: (message: string) => Effect.Effect<void, never, TraceService> = (message) =>
+  write(StatusUpdate, { message });

package/src/Trigger.ts

@@ -0,0 +1,196 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { DXN, Annotation, Feed, Obj, QueryAST, Ref, Type, type Query } from '@dxos/echo';
+import { HiddenAnnotation } from '@dxos/echo/Annotation';
+import { OptionsAnnotationId } from '@dxos/echo/Format';
+
+/**
+ * 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', 'feed', '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(wittjosiah): Remove. Migrate to Subscription triggers once EDGE supports them for feed queries.
+export const FeedSpec = Schema.Struct({
+  kind: Schema.Literal('feed').annotations(kindLiteralAnnotations),
+  feed: Schema.optional(Ref.Ref(Feed.Feed).annotations({ title: 'Feed' })),
+});
+export type FeedSpec = Schema.Schema.Type<typeof FeedSpec>;
+
+/**
+ * Construct a Feed trigger spec from a Feed object.
+ */
+export const specFeed = (feed: Feed.Feed): FeedSpec => ({
+  kind: 'feed',
+  feed: Ref.make(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, FeedSpec, 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: { '/': 'echo://AAA/ZZZ' }
+   * }
+   */
+  input: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Any })),
+}).pipe(
+  Annotation.IconAnnotation.set({ icon: 'ph--lightning--regular', hue: 'yellow' }),
+  HiddenAnnotation.set(true),
+  Type.makeObject(DXN.make('org.dxos.type.trigger', '0.1.0')),
+);
+
+export type Trigger = Type.InstanceType<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/TriggerEvent.ts

@@ -0,0 +1,64 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { Feed, 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 FeedEvent = Schema.Struct({
+  feed: Ref.Ref(Feed.Feed),
+  item: Schema.Any,
+  cursor: Schema.String,
+});
+export type FeedEvent = Schema.Schema.Type<typeof FeedEvent>;
+
+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, FeedEvent, SubscriptionEvent, TimerEvent, WebhookEvent);
+export type TriggerEvent = Schema.Schema.Type<typeof TriggerEvent>;

package/src/errors.ts

@@ -0,0 +1,71 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { BaseError, type BaseErrorOptions } from '@dxos/errors';
+
+// Errors from @dxos/operation.
+
+export class InvokerNotInitializedError extends BaseError.extend(
+  'InvokerNotInitializedError',
+  'Invoker not initialized',
+) {
+  constructor() {
+    super();
+  }
+}
+
+export class NoHandlerError extends BaseError.extend('NoHandlerError', 'No handler found for operation. ') {
+  constructor(operationKey: string) {
+    super({ context: { operationKey } });
+  }
+}
+
+// Errors from @dxos/functions.
+
+export class ServiceNotAvailableError extends BaseError.extend('ServiceNotAvailable', 'Service not available') {
+  constructor(service: string, options?: Omit<BaseErrorOptions, 'context'>) {
+    super({ context: { service }, message: `Service not available: ${service}`, ...options });
+  }
+}
+
+export class FunctionNotFoundError extends BaseError.extend('FunctionNotFound', 'Function not found') {
+  constructor(functionKey: string, options?: Omit<BaseErrorOptions, 'context'>) {
+    super({ context: { function: functionKey }, ...options });
+  }
+}
+
+export class FunctionError extends BaseError.extend('FunctionError', 'Function invocation error') {}
+
+export class InvalidOperationInputError extends BaseError.extend(
+  'InvalidOperationInput',
+  'Operation input did not match schema',
+) {}
+
+export class InvalidOperationOutputError extends BaseError.extend(
+  'InvalidOperationOutput',
+  'Operation output did not match schema',
+) {}
+
+export class TriggerStateNotFoundError extends BaseError.extend('TriggerStateNotFound', 'Trigger state not found') {}
+
+/**
+ * Raised when the upstream AI gateway responds with a structured JSON error envelope
+ * (`{ "type": "error", "error": { "type": ..., "message": ... } }`). Surfaces as a typed
+ * defect from `FunctionsAiHttpClient`, bypassing `@effect/ai`'s generic `HttpResponseError`
+ * wrapping so callers can match on the error class directly.
+ */
+export class FunctionsAiUpstreamError extends BaseError.extend(
+  'FunctionsAiUpstreamError',
+  'Upstream AI service returned an error',
+) {}
+
+/**
+ * Specialized `FunctionsAiUpstreamError` for the memoization layer: the recorded fixture for a
+ * given cache key was not found and `ALLOW_LLM_GENERATION` is unset. The `cacheKey` is exposed
+ * via `context.cacheKey` to make regeneration straightforward.
+ */
+export class FunctionsAiMemoizationMissError extends BaseError.extend(
+  'FunctionsAiMemoizationMissError',
+  'No memoized AI conversation found for the given cache key',
+) {}