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

package/src/Operation.ts

@@ -0,0 +1,646 @@
+//
+// Copyright 2025 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 Option from 'effect/Option';
+import * as Pipeable from 'effect/Pipeable';
+import * as Schema$ from 'effect/Schema';
+import type * as Types from 'effect/Types';
+
+import { DXN, Annotation, JsonSchema, Migration, Obj, Ref, Type, type Key } from '@dxos/echo';
+import type { URI } from '@dxos/keys';
+
+import type { NoHandlerError } from './errors';
+import type { Operation } from './index';
+
+/**
+ * Schema type that accepts any Encoded form but requires no Context.
+ * This allows ECHO object schemas where Type !== Encoded due to [KindId] symbol.
+ */
+type Schema<T> = Schema$.Schema<T, any, never>;
+
+export const DefinitionTypeId = '~@dxos/operation/OperationDefinition' as const;
+export type DefinitionTypeId = typeof DefinitionTypeId;
+
+/**
+ * Serializable definition of an Operation.
+ * Contains schema and metadata, but no runtime logic.
+ */
+export interface Definition<I, O, S = any> extends Pipeable.Pipeable, Definition.Variance<I, O, S> {
+  /**
+   * Input schema for the operation.
+   */
+  readonly input: Schema<I>;
+  /**
+   * Output schema for the operation.
+   */
+  readonly output: Schema<O>;
+
+  readonly meta: {
+    readonly key: DXN.DXN;
+    readonly name?: string;
+    readonly version?: string;
+    readonly description?: string;
+    /**
+     * Phosphor icon identifier in `ph--<name>--<variant>` format (e.g. `ph--file-text--regular`).
+     */
+    readonly icon?: string;
+    /**
+     * Deployment ID for remote invocation.
+     * Assigned by the EDGE function service when deployed.
+     */
+    readonly deployedId?: string;
+
+    /**
+     * Dictionary of annotations for the operation.
+     */
+    // TODO(dmaretskyi): Make required, but this complicates `make` to fill in defaults.
+    readonly annotations?: Annotation.Dictionary;
+
+    /**
+     * When true, this operation is not serialized into the hypergraph registry.
+     * Use for UI-only operations that should not be discoverable by the AI agent.
+     */
+    readonly skipRegistry?: boolean;
+  };
+
+  /**
+   * Execution mode for the operation.
+   * - 'sync': Operation completes synchronously (fast, UI-blocking acceptable).
+   * - 'async': Operation may take time (should not block UI).
+   */
+  readonly executionMode: 'sync' | 'async';
+
+  /**
+   * ECHO types the operation uses.
+   * Ensures types are available when the operation is executed remotely.
+   */
+  readonly types: readonly Type.AnyEntity[];
+
+  /**
+   * Effect services required by this operation.
+   * These services will be automatically provided to the handler at invocation time.
+   */
+  readonly services: readonly Context.Tag<any, any>[];
+}
+
+/**
+ * Namespace for OperationDefinition helper types.
+ */
+export declare namespace Definition {
+  export interface Variance<I, O, S> {
+    [DefinitionTypeId]: {
+      readonly _Input: Types.Contravariant<I>;
+      readonly _Output: Types.Covariant<O>;
+      readonly _Services: Types.Covariant<S>;
+    };
+  }
+
+  /**
+   * Any operation definition, regardless of input/output types.
+   */
+  export type Any = Definition<any, any, any>;
+
+  /**
+   * Extract the input type from an operation definition.
+   */
+  export type Input<T extends Any> = T extends Variance<infer I, infer _O, infer _S> ? I : never;
+
+  /**
+   * Extract the output type from an operation definition.
+   */
+  export type Output<T extends Any> = T extends Variance<infer _I, infer O, infer _S> ? O : never;
+
+  /**
+   * Extract the service identifier types from an operation's services array.
+   * Returns `never` if the operation has no services declared.
+   */
+  export type Services<T extends Any> = T extends Variance<infer _I, infer _O, infer S> ? S : never;
+
+  export type HandlerType<T extends Any> =
+    T extends Variance<infer I, infer O, infer S> ? Handler<I, O, any, S> : never;
+}
+
+/**
+ * Runtime handler for an Operation.
+ */
+export type Handler<I, O, E = Error, R = never> = (input: I) => Effect.Effect<O, E, R>;
+
+export type WithHandler<T extends Definition.Any> = T & {
+  handler: Definition.HandlerType<T>;
+};
+
+/**
+ * Checks if a value is an operation definition.
+ */
+export const isOperationDefinition = (value: unknown): value is Definition.Any => {
+  return typeof value === 'object' && value !== null && DefinitionTypeId in value;
+};
+
+/**
+ * Checks if a value is an operation with a handler.
+ */
+export const isOperationWithHandler = (value: unknown): value is WithHandler<Definition.Any> => {
+  return isOperationDefinition(value) && 'handler' in value;
+};
+
+/**
+ * Props for creating an Operation definition.
+ * Derived from OperationDefinition with executionMode made optional (defaults to 'async').
+ */
+export type Props<I, O> = Omit<Definition<I, O>, DefinitionTypeId | 'pipe' | 'executionMode' | 'types' | 'services'> & {
+  readonly executionMode?: 'sync' | 'async';
+  readonly types?: Definition<I, O>['types'];
+  readonly services?: Definition<I, O>['services'];
+};
+
+/**
+ * Creates a new Operation definition.
+ * Applies default executionMode of 'async' if not specified.
+ * The returned type preserves the literal types of props (including services).
+ */
+export const make = <const P extends Types.NoExcessProperties<Props<any, any>, P>>(
+  props: P,
+): Definition<
+  Schema$.Schema.Type<P['input']>,
+  Schema$.Schema.Type<P['output']>,
+  Context.Tag.Identifier<NonNullable<P['services']>[number]>
+> => {
+  return {
+    [DefinitionTypeId]: {},
+    ...props,
+    executionMode: props.executionMode ?? 'async',
+    types: props.types ?? [],
+    services: props.services ?? [],
+    pipe() {
+      // eslint-disable-next-line prefer-rest-params
+      return Pipeable.pipeArguments(this, arguments);
+    },
+  } as any;
+};
+
+/**
+ * Attaches a handler to an Operation definition.
+ * The handler may use any services declared in the operation, plus Operation.Service (always available).
+ * Dual API: can be called directly or used in a pipe.
+ *
+ * @example
+ * ```ts
+ * const MyOp = Operation.make({
+ *   input: Schema.Void,
+ *   output: Schema.Void,
+ *   meta: { key: 'my-op' },
+ *   services: [DatabaseService],
+ * });
+ *
+ * // Direct call - handler can use DatabaseService
+ * const op = Operation.withHandler(MyOp, (input) =>
+ *   Effect.gen(function* () {
+ *     const db = yield* DatabaseService;
+ *     return {};
+ *   }),
+ * );
+ *
+ * // Piped call
+ * const op = MyOp.pipe(Operation.withHandler((input) => Effect.succeed({})));
+ * ```
+ */
+export const withHandler: {
+  <Def extends Definition<any, any>, E = never>(
+    handler: Handler<Definition.Input<Def>, Definition.Output<Def>, E, Definition.Services<Def> | Service>,
+  ): (op: Def) => WithHandler<Def>;
+  <Def extends Definition<any, any>, E = never>(
+    op: Def,
+    handler: Handler<Definition.Input<Def>, Definition.Output<Def>, E, Definition.Services<Def> | Service>,
+  ): WithHandler<Def>;
+} = <Def extends Definition<any, any>, E = never>(
+  opOrHandler: Def | Handler<Definition.Input<Def>, Definition.Output<Def>, E, Definition.Services<Def> | Service>,
+  handler?: Handler<Definition.Input<Def>, Definition.Output<Def>, E, Definition.Services<Def> | Service>,
+): WithHandler<Def> => {
+  // If called with just handler (piped usage).
+  if (handler === undefined) {
+    const handlerFn = opOrHandler as Handler<
+      Definition.Input<Def>,
+      Definition.Output<Def>,
+      E,
+      Definition.Services<Def> | Service
+    >;
+    return ((op: Def) => ({
+      ...op,
+      handler: handlerFn,
+    })) as any;
+  }
+
+  // If called with both op and handler (direct usage).
+  const op = opOrHandler as Def;
+  return {
+    ...op,
+    handler,
+  } as any;
+};
+
+/**
+ * Helper to make the handler type opaque.
+ * Workaround for TypeScript's inability to infer the handler type from the operation definition:
+ * ```
+ * error TS2742: The inferred type of 'default' cannot be named without a reference.
+ * ```
+ *
+ * Most of the time the exact handler type is not needed.
+ *
+ * @example
+ * ```ts
+ * const MyOp = Operation.make({
+ *   input: Schema.Void,
+ *   output: Schema.Void,
+ *   meta: { key: 'my-op' },
+ *   services: [DatabaseService],
+ * });
+ *
+ * export default MyOp.pipe(
+ *   Operation.withHandler(
+ *     Effect.fn(function* (input) {
+ *       return { result: 'ok' };
+ *     }),
+ *   ),
+ *   Operation.opaqueHandler,
+ * );
+ * ```
+ */
+export const opaqueHandler = <T extends Operation.Definition.Any>(
+  handler: Operation.WithHandler<T>,
+): Operation.WithHandler<Operation.Definition.Any> => handler;
+
+//
+// Invocation Interfaces
+//
+
+/**
+ * Local invocation of an operation.
+ */
+export type Invoke = <I, O, E>(op: Definition<I, O>, input: I) => Effect.Effect<O, E>;
+
+/**
+ * Remote invocation of an operation.
+ */
+export type InvokeRemote = <I, O, E>(
+  op: Definition<I, O>,
+  input: I,
+  options?: { timeout?: number },
+) => Effect.Effect<O, E>;
+
+/**
+ * Database record of an operation.
+ * The registry `key` and `version` live in the object meta — access via
+ * `Obj.getMeta(record).key` and `Obj.getMeta(record).version`.
+ */
+export const PersistentOperation = Schema$.Struct({
+  name: Schema$.NonEmptyString,
+
+  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(Obj.Unknown)),
+
+  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.
+  // TODO(dmaretskyi): Add this field to Operation.Definition.
+  binding: Schema$.optional(Schema$.String),
+
+  /**
+   * Phosphor icon identifier in `ph--<name>--<variant>` format (e.g. `ph--file-text--regular`).
+   */
+  icon: Schema$.optional(Schema$.String),
+}).pipe(
+  Annotation.LabelAnnotation.set(['name']),
+  Annotation.IconAnnotation.set({ icon: 'ph--function--regular', hue: 'blue' }),
+  Annotation.HiddenAnnotation.set(true),
+  // TODO(dmaretskyi): Keep typename as 'org.dxos.type.function' (not 'operation') to maintain
+  //  backward compatibility with existing data and avoid requiring data migration.
+  Type.makeObject(DXN.make('org.dxos.type.function', '0.2.0')),
+);
+export type PersistentOperation = Type.InstanceType<typeof PersistentOperation>;
+
+const FUNCTION_META_KEY = 'org.dxos.service.function';
+
+/**
+ * Get the registry key for a persistent operation record (from the object meta).
+ */
+export const getKey = (record: PersistentOperation): string | undefined => Obj.getMeta(record).key;
+
+/**
+ * Get the registry version for a persistent operation record (from the object meta).
+ */
+export const getVersion = (record: PersistentOperation): string | undefined => Obj.getMeta(record).version;
+
+/**
+ * Serialize an operation definition to a persistent operation record.
+ */
+export const serialize = (operation: Definition.Any): PersistentOperation => {
+  return Obj.make(PersistentOperation, {
+    [Obj.Meta]: {
+      key: operation.meta.key,
+      version: operation.meta.version ?? '0.0.0',
+      keys: operation.meta.deployedId ? [{ source: FUNCTION_META_KEY, id: operation.meta.deployedId }] : [],
+      annotations: operation.meta.annotations,
+    },
+    name: operation.meta.name ?? '',
+    description: operation.meta.description,
+    icon: operation.meta.icon,
+    updated: undefined,
+    source: undefined,
+    inputSchema: JsonSchema.toJsonSchema(operation.input),
+    outputSchema: JsonSchema.toJsonSchema(operation.output),
+    services: operation.services.map((service) => service.key),
+  });
+};
+
+/**
+ * Deserialize a persistent operation record to an operation definition.
+ */
+export const deserialize = (record: PersistentOperation): Definition.Any => {
+  const meta = Obj.getMeta(record);
+  // Extract deployed function ID from ECHO meta keys (matches FUNCTIONS_META_KEY in @dxos/functions).
+  const deployedId = meta.keys.find((key) => key.source === FUNCTION_META_KEY)?.id;
+  return make({
+    input: record.inputSchema ? JsonSchema.toEffectSchema(record.inputSchema) : Schema$.Unknown,
+    output: record.outputSchema ? JsonSchema.toEffectSchema(record.outputSchema) : Schema$.Unknown,
+    services: record.services?.map((service) => Context.GenericTag(service)) ?? [],
+    executionMode: 'async',
+    types: [],
+    meta: {
+      key: DXN.tryMake(meta.key ?? record.name) ?? DXN.make(meta.key ?? record.name),
+      name: record.name,
+      version: meta.version ?? '0.0.0',
+      description: record.description,
+      icon: record.icon,
+      deployedId,
+      annotations: meta.annotations ?? {},
+    },
+  });
+};
+
+/**
+ * Update properties on the target operation record from the source operation record.
+ */
+export const setFrom = (target: PersistentOperation, source: PersistentOperation) => {
+  Obj.update(target, (target) => {
+    target.name = source.name ?? target.name;
+    target.description = source.description;
+    target.icon = source.icon;
+    target.updated = source.updated;
+    // TODO(dmaretskyi): A workaround for an ECHO bug.
+    target.inputSchema = source.inputSchema ? JSON.parse(JSON.stringify(source.inputSchema)) : undefined;
+    target.outputSchema = source.outputSchema ? JSON.parse(JSON.stringify(source.outputSchema)) : undefined;
+    const sourceMeta = Obj.getMeta(source);
+    const targetMeta = Obj.getMeta(target);
+    targetMeta.key = sourceMeta.key ?? targetMeta.key;
+    targetMeta.version = sourceMeta.version;
+    // Only overwrite foreign keys when the source actually carries them; otherwise we'd wipe
+    // bindings (e.g. the deployedId set by `deserialize`) on records produced by `serialize`.
+    if (sourceMeta.keys.length > 0) {
+      targetMeta.keys = JSON.parse(JSON.stringify(sourceMeta.keys));
+    }
+    targetMeta.annotations = sourceMeta.annotations ?? targetMeta.annotations;
+  });
+};
+
+/**
+ * Translatable label — a plain string or an i18next-style `[key, options]` tuple.
+ * Defined locally to avoid a core dependency on UI translation packages; structurally compatible with
+ * the app-level `Label` type so values flow into UI toasts unchanged.
+ */
+export type Label = string | [string, { ns: string | readonly string[]; count?: number; defaultValue?: string }];
+
+/**
+ * Per-phase user notification messages for an invocation.
+ * A phase is notified to the user iff its message is provided; messages are translatable {@link Label}s.
+ */
+export interface NotifyOptions {
+  /** Shown when the invocation starts. */
+  start?: Label;
+  /** Shown when the invocation succeeds. */
+  success?: Label;
+  /** Shown when the invocation fails. */
+  error?: Label;
+}
+
+/**
+ * Options for operation invocation.
+ */
+export interface InvokeOptions {
+  /**
+   * Space ID to provide database context for the handler.
+   */
+  spaceId?: Key.SpaceId;
+  /**
+   * Request user-facing notifications at the given invocation phases.
+   */
+  notify?: NotifyOptions;
+  /**
+   * URI of the conversation feed (queue) — today always an EID, but typed as
+   * `URI.URI` to accommodate future entity-kind extensions. Narrow with `EID.parse`
+   * at the point of use.
+   * Passed to the process environment so nested operations can resolve AiContext.Service and related services.
+   */
+  conversation?: URI.URI;
+  /**
+   * Optional process-runtime tracing metadata (consumed by `@dxos/functions-runtime` when wired).
+   */
+  tracing?: unknown;
+}
+
+/**
+ * Annotation that marks an operation as idempotent — safe to retry even if a previous execution
+ * was interrupted mid-handler. When absent the operation is treated as non-idempotent, and the
+ * process runtime will fail (rather than re-run) any handler that was interrupted.
+ */
+export const IdempotentAnnotation = Annotation.make({
+  id: 'org.dxos.operation.idempotent',
+  schema: Schema$.Boolean,
+});
+
+/**
+ * Returns true when the operation is explicitly annotated as idempotent.
+ */
+export const isIdempotent = (op: Definition.Any): boolean =>
+  op.meta.annotations
+    ? Option.getOrElse(Annotation.getDictionary(op.meta.annotations, IdempotentAnnotation), () => false)
+    : false;
+
+/**
+ * Operation service interface - provides unified access to operation invocation and scheduling.
+ * This service is automatically provided to operation handlers.
+ */
+export interface OperationService {
+  /**
+   * Invoke an operation as an Effect.
+   * Returns an Effect that resolves to the operation output.
+   */
+  invoke: <I, O>(
+    op: Operation.Definition<I, O>,
+    ...args: void extends I ? [input?: I, options?: InvokeOptions] : [input: I, options?: InvokeOptions]
+  ) => Effect.Effect<O, NoHandlerError>;
+
+  /**
+   * Schedule an operation to run as a followup.
+   * The followup is tracked and won't be cancelled when the parent operation completes.
+   * Returns an Effect that completes immediately after scheduling.
+   */
+  schedule: <I, O>(
+    op: Operation.Definition<I, O>,
+    ...args: void extends I ? [input?: I, options?: InvokeOptions] : [input: I, options?: InvokeOptions]
+  ) => Effect.Effect<void>;
+
+  /**
+   * Invoke an operation and return a Promise.
+   * Useful for async contexts where Effect is not available.
+   */
+  invokePromise: <I, O>(
+    op: Operation.Definition<I, O>,
+    ...args: void extends I ? [input?: I, options?: InvokeOptions] : [input: I, options?: InvokeOptions]
+  ) => Promise<{ data?: O; error?: Error }>;
+}
+
+/**
+ * Context tag for the Operation service.
+ * Operation handlers can yield this to invoke other operations or schedule followups.
+ *
+ * @example
+ * ```ts
+ * const handler = (input) => Effect.gen(function* () {
+ *   // Schedule a followup (fire and forget)
+ *   yield* Operation.schedule(AnalyticsOperation, { event: 'completed' });
+ *
+ *   // Invoke another operation
+ *   return yield* Operation.invoke(OtherOperation, { data: input.data });
+ * });
+ * ```
+ */
+// TODO(dmaretskyi): Rename Operation.Invoker
+export class Service extends Context.Tag('@dxos/operation/Service')<Service, OperationService>() {}
+
+//
+// Namespace functions - ergonomic access to Operation.Service methods.
+//
+
+/**
+ * Invoke an operation as an Effect.
+ * Yields the Operation.Service internally.
+ *
+ * @example
+ * ```ts
+ * yield* Operation.invoke(MyOperation, { data: 'test' });
+ * ```
+ */
+export const invoke = <I, O>(
+  op: Operation.Definition<I, O>,
+  ...args: void extends I ? [input?: I, options?: InvokeOptions] : [input: I, options?: InvokeOptions]
+): Effect.Effect<O, NoHandlerError, Service> =>
+  Effect.flatMap(Service, (ops) => ops.invoke(op, ...(args as [I, InvokeOptions?]))).pipe(
+    Effect.withSpan('Operation.invoke'),
+  );
+
+/**
+ * Schedule an operation to run as a followup.
+ * Yields the Operation.Service internally.
+ *
+ * @example
+ * ```ts
+ * yield* Operation.schedule(AnalyticsOperation, { event: 'completed' });
+ * yield* Operation.schedule(VoidOperation); // input optional when void
+ * ```
+ */
+export const schedule = <I, O>(
+  op: Operation.Definition<I, O>,
+  ...args: void extends I ? [input?: I, options?: InvokeOptions] : [input: I, options?: InvokeOptions]
+): Effect.Effect<void, never, Service> =>
+  Effect.flatMap(Service, (ops) => ops.schedule(op, ...(args as [I, InvokeOptions?]))).pipe(
+    Effect.withSpan('Operation.schedule'),
+  );
+
+/**
+ * Provides additional invocation options to all invocations.
+ */
+export const withInvocationOptions = (options: InvokeOptions): Layer.Layer<Service, never, Service> =>
+  Layer.effect(
+    Service,
+    Effect.gen(function* () {
+      const service = yield* Service;
+      return Service.of({
+        invoke: ((op: Operation.Definition.Any, input: any, invocationOptions: InvokeOptions) =>
+          service.invoke(op, input, { ...options, ...invocationOptions })) as any,
+        invokePromise: ((op: Operation.Definition.Any, input: any, invocationOptions: InvokeOptions) =>
+          service.invokePromise(op, input, { ...options, ...invocationOptions })) as any,
+        schedule: ((op: Operation.Definition.Any, input: any, invocationOptions: InvokeOptions) =>
+          service.schedule(op, input, { ...options, ...invocationOptions })) as any,
+      });
+    }),
+  );
+
+//
+// Legacy schemas and migrations.
+//
+
+/**
+ * Persistent operation schema v0.1.0 — `key` and `version` are stored as data properties.
+ * @deprecated Use {@link PersistentOperation} (v0.2.0) instead; the `key` and `version` now live in the object meta.
+ */
+export const PersistentOperation_v0_1_0 = Schema$.Struct({
+  key: Schema$.optional(Schema$.String),
+  name: Schema$.NonEmptyString,
+  version: Schema$.String,
+  description: Schema$.optional(Schema$.String),
+  updated: Schema$.optional(Schema$.String),
+  source: Schema$.optional(Ref.Ref(Obj.Unknown)),
+  inputSchema: Schema$.optional(JsonSchema.JsonSchema),
+  outputSchema: Schema$.optional(JsonSchema.JsonSchema),
+  services: Schema$.optional(Schema$.Array(Schema$.String)),
+  binding: Schema$.optional(Schema$.String),
+}).pipe(Type.makeObject(DXN.make('org.dxos.type.function', '0.1.0')));
+export type PersistentOperation_v0_1_0 = Type.InstanceType<typeof PersistentOperation_v0_1_0>;
+
+/**
+ * Migration from {@link PersistentOperation_v0_1_0} (v0.1.0) to {@link PersistentOperation} (v0.2.0).
+ * Moves `key` and `version` from the data section into the object meta.
+ */
+const _migration = Migration.define({
+  from: PersistentOperation_v0_1_0,
+  to: PersistentOperation,
+  transform: async (from) => ({
+    [Obj.Meta]: { key: from.key, version: from.version },
+    name: from.name,
+    description: from.description,
+    updated: from.updated,
+    source: from.source as any,
+    inputSchema: from.inputSchema,
+    outputSchema: from.outputSchema,
+    services: from.services,
+    binding: from.binding,
+  }),
+});
+
+/**
+ * Schema migrations exported by this module.
+ * Exported as an array for extensibility — append future versions here.
+ */
+export const migrations = [_migration];