@dxos/functions 0.8.4-main.bc674ce → 0.8.4-main.bcb3aa67d6

package/src/process/Process.ts

@@ -0,0 +1,457 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Scope from 'effect/Scope';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import type * as Exit from 'effect/Exit';
+import * as Context from 'effect/Context';
+import type * as Types from 'effect/Types';
+
+import { Operation, OperationHandlerSet } from '@dxos/operation';
+import type { TracingService } from '../services/tracing';
+import * as Option from 'effect/Option';
+import type { Atom } from '@effect-atom/atom';
+import type { ObjectId } from '@dxos/protocols';
+import { assertArgument } from '@dxos/invariant';
+import * as Trace from '../Trace';
+
+//
+// Process.
+//
+
+/** Opaque process id (arbitrary string). */
+export const ID = Schema.String.pipe(Schema.brand('ProcessId'));
+export type ID = Schema.Schema.Type<typeof ID>;
+
+/**
+ * A running process callbacks.
+ *
+ * Process lifecycle: Initial -> Running <-> Suspended -> Terminated.
+ *
+ * - onSpawn -> called once when the process is spawned.
+ * - onInput -> called for every input submitted to the process.
+ * - onAlarm -> called for processes scheduling alarms.
+ * - onChildEvent -> called when child process produces output or exits.
+ */
+export interface Callbacks<I, O, R> {
+  /**
+   * Called when the process is spawned.
+   * Not called for processes that are resumed from a previously suspended state.
+   *
+   * @returns A signal indicating to the runtime whether the process is finished, or should be resumed later.
+   * @throws Throwing in the handler will terminate the process with an error.
+   *
+   * Note: This function should aim to complete in under 5 seconds to avoid exceeding limits in serverless environments.
+   */
+  onSpawn(): Effect.Effect<void, never, R | BaseServices>;
+
+  /**
+   * Called when there's input available to process.
+   *
+   * The function can be called in parallel.
+   *
+   * @returns A signal indicating to the runtime whether the process is finished, or should be resumed later.
+   * @throws Throwing in the handler will terminate the process with an error.
+   *
+   * Note: This function should aim to complete in under 5 seconds to avoid exceeding limits in serverless environments.
+   */
+  onInput(input: I): Effect.Effect<void, never, R | BaseServices>;
+
+  /**
+   * Called when the process's alarm is triggered.
+   *
+   * @throws Throwing in the handler will terminate the process with an error.
+   */
+  onAlarm(): Effect.Effect<void, never, R | BaseServices>;
+
+  /**
+   * Called when the process's child process produces output or exits.
+   *
+   * This allows the parent process to hibernate while a long-running child process is running.
+   */
+  onChildEvent(event: ChildEvent<unknown>): Effect.Effect<void, never, R | BaseServices>;
+}
+
+/**
+ * Services that are always available to all processes.
+ */
+export type BaseServices = TracingService | Trace.TraceService;
+
+export type ChildEvent<T> =
+  | {
+      readonly _tag: 'output';
+      readonly pid: ID;
+      readonly data: T;
+    }
+  | {
+      readonly _tag: 'exited';
+      readonly pid: ID;
+      readonly result: Exit.Exit<void>;
+    };
+
+export interface ProcessContext<I, O> {
+  readonly id: ID;
+
+  /**
+   * Parameters assigned during process creation.
+   */
+  readonly params: Params;
+
+  /**
+   * Complete this process with sucessful result.
+   * No additional events will be pushed to the process.
+   */
+  succeed(): void;
+
+  /**
+   * Complete this process with an error.
+   * No additional events will be pushed to the process.
+   */
+  fail(error: Error): void;
+
+  /**
+   * Submit output of the process.
+   */
+  submitOutput(output: O): void;
+
+  /**
+   * Set an alarm for the process to be woken up later.
+   *
+   * @param timeout - Optional timeout in milliseconds. If not provided, the process is woken up as soon as possible.
+   */
+  setAlarm(timeout?: number): void;
+}
+
+/**
+ * Generic parameters for a all processes.
+ */
+export interface Params {
+  /**
+   * Process name for debugging purposes.
+   */
+  readonly name: string | null;
+
+  /**
+   * Target object that this process is assigned to.
+   */
+  readonly target: ObjectId | null;
+}
+
+//
+// Executable.
+//
+
+export const ProcessTypeId = '~@dxos/functions/Process' as const;
+export type ProcessTypeId = typeof ProcessTypeId;
+
+/**
+ * A process (factory).
+ * Can be instantiated mutlitple times to produce new runtime instance with separate state and callbacks.
+ * `create` is used to instantiate a new process.
+ * Can store runtime state in scope of `create` function.
+ */
+export interface Process<I, O, R> extends Process.Variance<I, O, R> {
+  /**
+   * Unique identifier for the executable in the reverse DNS format.
+   */
+  readonly key: string;
+
+  /**
+   * Human-readable label from {@link MakeExecutableOpts.name} when provided.
+   */
+  readonly name?: string;
+
+  readonly services: readonly Context.Tag<any, any>[];
+
+  /**
+   * Create a new instance of the process.
+   */
+  create(ctx: ProcessContext<I, O>): Effect.Effect<Callbacks<I, O, R>, never, R | BaseServices | Scope.Scope>;
+}
+
+export const isProcess = (executable: unknown): executable is Process.Any =>
+  typeof executable === 'object' && executable !== null && ProcessTypeId in executable;
+
+export namespace Process {
+  export interface Variance<I, O, R> {
+    readonly [ProcessTypeId]: {
+      readonly _Input: Types.Contravariant<I>;
+      readonly _Output: Types.Covariant<O>;
+      readonly _Requirements: Types.Covariant<R>;
+    };
+  }
+
+  export type Any = Process<any, any, never>;
+}
+
+export interface MakeProcessOpts {
+  /**
+   * Unique identifier for the process in the reverse DNS format.
+   */
+  readonly key: string;
+
+  readonly input: Schema.Schema.AnyNoContext;
+  readonly output: Schema.Schema.AnyNoContext;
+  readonly services: readonly Context.Tag<any, any>[];
+}
+
+export const make = <const Opts extends Types.NoExcessProperties<MakeProcessOpts, Opts>>(
+  opts: Opts,
+  create: (
+    ctx: ProcessContext<Schema.Schema.Type<Opts['input']>, Schema.Schema.Type<Opts['output']>>,
+  ) => Effect.Effect<
+    Partial<
+      Callbacks<
+        Schema.Schema.Type<Opts['input']>,
+        Schema.Schema.Type<Opts['output']>,
+        Context.Tag.Identifier<NonNullable<Opts['services']>[number]>
+      >
+    >,
+    never,
+    Context.Tag.Identifier<NonNullable<Opts['services']>[number]> | BaseServices | Scope.Scope
+  >,
+): Process<
+  Schema.Schema.Type<Opts['input']>,
+  Schema.Schema.Type<Opts['output']>,
+  Context.Tag.Identifier<NonNullable<Opts['services']>[number]>
+> => {
+  assertArgument(/^[a-z0-9]([a-z0-9.\-/]*[a-z0-9])?$/i.test(opts.key), 'key', 'Invalid key');
+  return {
+    [ProcessTypeId]: {} as any,
+    ...opts,
+    create: (ctx) =>
+      create(ctx).pipe(
+        Effect.map((partial) => ({
+          onSpawn: () => Effect.void,
+          onInput: () => Effect.void,
+          onAlarm: () => Effect.void,
+          onChildEvent: () => Effect.void,
+          ...partial,
+        })),
+      ),
+  };
+};
+
+export const fromOperation = <const Op extends Operation.Definition.Any>(
+  op: Op,
+  handler: OperationHandlerSet.OperationHandlerSet,
+): Process<Operation.Definition.Input<Op>, Operation.Definition.Output<Op>, Operation.Definition.Services<Op>> =>
+  make(
+    {
+      key: op.meta.key,
+      input: op.input,
+      output: op.output,
+      services: op.services,
+    },
+    (ctx) =>
+      Effect.gen(function* () {
+        const semaphore = yield* Effect.makeSemaphore(1);
+
+        return {
+          onInput: (input: Operation.Definition.Input<Op>) =>
+            Effect.gen(function* () {
+              const opHandler = yield* OperationHandlerSet.getHandler(handler, op).pipe(Effect.orDie);
+              const output = yield* opHandler.handler(input).pipe(Effect.orDie) as Effect.Effect<
+                Operation.Definition.Output<Op>,
+                never,
+                never
+              >;
+
+              ctx.submitOutput(output);
+              ctx.succeed();
+            }).pipe(semaphore.withPermits(1)),
+        };
+      }),
+  );
+
+/**
+ * Runtime state of a process.
+ */
+export enum State {
+  // Process is actively running.
+  RUNNING = 'RUNNING',
+
+  // Process is waiting for a child process to complete or an alarm to trigger.
+  HYBERNATING = 'HYBERNATING',
+
+  // Process is waiting for input. It will only resume when input is submitted.
+  IDLE = 'IDLE',
+
+  // Process is terminating and will transition to TERMINATED state.
+  // TODO(dmaretskyi): Consider removing.
+  TERMINATING = 'TERMINATING',
+
+  // Process has been externally terminated.
+  TERMINATED = 'TERMINATED',
+
+  // Process has completed successfully.
+  SUCCEEDED = 'SUCCEEDED',
+
+  // Process has failed.
+  FAILED = 'FAILED',
+}
+
+/**
+ * Read-only view of a process tree
+ */
+export interface Monitor {
+  /**
+   * Get the current state of the process tree.
+   */
+  processTree: Effect.Effect<readonly Info[]>;
+
+  /**
+   * Atom for the process tree.
+   */
+  processTreeAtom: Atom.Atom<readonly Info[]>;
+}
+
+export class ProcessMonitorService extends Context.Tag('@dxos/functions/ProcessMonitorService')<
+  ProcessMonitorService,
+  Monitor
+>() {}
+
+export interface Info {
+  readonly pid: ID;
+  readonly parentPid: ID | null;
+
+  /**
+   * Key of the process.
+   *
+   * NOTE: There might be multiple running processes with the same key.
+   */
+  readonly key: string;
+
+  /**
+   * Parameters of the process.
+   */
+  readonly params: Params;
+
+  /**
+   * State of the process.
+   */
+  readonly state: State;
+
+  /**
+   * Error of the process.
+   * Only for process in FAILED state.
+   */
+  readonly error: string | null;
+
+  /**
+   * UNIX timestamp in milliseconds.
+   */
+  readonly startedAt: number;
+
+  /**
+   * UNIX timestamp in milliseconds.
+   */
+  readonly completedAt: Option.Option<number>;
+
+  readonly metrics: {
+    /**
+     * Total wall time of all handler invocations of the process in milliseconds.
+     */
+    readonly wallTime: number;
+
+    /**
+     * Total number of inputs submitted to the process.
+     */
+    readonly inputCount: number;
+
+    /**
+     * Total number of outputs submitted to the process.
+     */
+    readonly outputCount: number;
+  };
+}
+
+/**
+ * New process is spawned.
+ */
+export const SpawnedEvent = Trace.EventType('process.spawned', {
+  schema: Schema.Void,
+  isEphemeral: false,
+});
+
+/**
+ * Process has reached a terminal state.
+ */
+export const ExitedEvent = Trace.EventType('process.exited', {
+  schema: Schema.Struct({
+    outcome: Schema.Literal('succeeded', 'failed', 'terminated'),
+  }),
+  isEphemeral: false,
+});
+
+/**
+ * Renders spawned processes as a forest: top-level rows use "- ", nested rows use ├── / └── / │.
+ */
+export const prettyProcessTree = (tree: readonly Info[]): string => {
+  if (tree.length === 0) {
+    return '';
+  }
+
+  const pidSet = new Set(tree.map((node) => node.pid));
+  const childrenByParent = new Map<string, Info[]>();
+  const roots: Info[] = [];
+
+  for (const node of tree) {
+    const parent = node.parentPid;
+    if (parent === null || !pidSet.has(parent)) {
+      roots.push(node);
+      continue;
+    }
+    const key = String(parent);
+    const siblings = childrenByParent.get(key) ?? [];
+    siblings.push(node);
+    childrenByParent.set(key, siblings);
+  }
+
+  const byPid = (a: Info, b: Info) => String(a.pid).localeCompare(String(b.pid));
+  roots.sort(byPid);
+  for (const siblings of childrenByParent.values()) {
+    siblings.sort(byPid);
+  }
+
+  const formatLabel = (node: Info): string => {
+    const idShort = String(node.pid).slice(0, 6);
+    const parts = [idShort, node.state];
+    if (node.params.name != null && node.params.name !== '') {
+      parts.push(node.params.name);
+    }
+    if (node.error != null) {
+      parts.push(`(${node.error})`);
+    }
+    const { inputCount, outputCount, wallTime } = node.metrics;
+    parts.push(`[in:${inputCount} out:${outputCount} wall:${Math.round(wallTime)}ms]`);
+    return parts.join(' ');
+  };
+
+  const lines: string[] = [];
+
+  const walk = (node: Info, prefix: string, isLast: boolean, isRoot: boolean): void => {
+    if (isRoot) {
+      lines.push(`- ${formatLabel(node)}`);
+    } else {
+      const branch = isLast ? '└── ' : '├── ';
+      lines.push(`${prefix}${branch}${formatLabel(node)}`);
+    }
+
+    const children = childrenByParent.get(String(node.pid)) ?? [];
+    const nextPrefix = isRoot ? '  ' : `${prefix}${isLast ? '    ' : '│   '}`;
+    children.forEach((child, index) => {
+      walk(child, nextPrefix, index === children.length - 1, false);
+    });
+  };
+
+  for (const root of roots) {
+    walk(root, '', true, true);
+  }
+
+  return lines.join('\n');
+};

package/src/process/ServiceResolver.ts

@@ -0,0 +1,173 @@
+//
+// 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 Option from 'effect/Option';
+import type { DXN, SpaceId } from '@dxos/keys';
+
+import { ServiceNotAvailableError } from '../errors';
+import * as Process from './Process';
+import * as Scope from 'effect/Scope';
+import * as Either from 'effect/Either';
+
+const ServiceResolverTypeId = '~@dxos/functions/ServiceResolver' as const;
+type ServiceResolverTypeId = typeof ServiceResolverTypeId;
+
+export interface ServiceResolver {
+  readonly [ServiceResolverTypeId]: ServiceResolverTypeId;
+
+  /**
+   * Resolve a set of services identified by their tags.
+   * Returns a Context containing all requested services, or fails with ServiceNotAvailableError.
+   */
+  resolve<Tag extends Context.Tag<any, any>>(
+    tag: Tag,
+    context: ResolutionContext,
+  ): Effect.Effect<Context.Tag.Service<Tag>, ServiceNotAvailableError, Scope.Scope>;
+}
+
+/**
+ * Tag for the ServiceResolver service.
+ */
+export const ServiceResolver = Context.GenericTag<ServiceResolver>('@dxos/functions/ServiceResolver');
+
+export const resolve = Effect.serviceFunctionEffect(ServiceResolver, (_) => _.resolve);
+
+export const resolveAll = <const Tags extends readonly Context.Tag<any, any>[]>(
+  tags: Tags,
+  context: ResolutionContext,
+): Effect.Effect<Context.Context<Tags[number]>, ServiceNotAvailableError, Scope.Scope | ServiceResolver> =>
+  Effect.gen(function* () {
+    const services = yield* Effect.forEach(tags, (tag) =>
+      resolve(tag, context).pipe(Effect.map((service) => Context.make(tag, service))),
+    );
+    return Context.mergeAll(...services);
+  });
+
+/**
+ * Provides context for service resolution.
+ */
+export interface ResolutionContext {
+  /**
+   * Under which identity the process is running.
+   */
+  readonly identity?: string;
+
+  /**
+   * Under which space the process is running.
+   */
+  readonly space?: SpaceId;
+
+  /**
+   * DXN of the conversation feed the process is running in.
+   */
+  readonly conversation?: DXN.String;
+
+  /**
+   * Under which process the process is running.
+   */
+  readonly process?: Process.ID;
+}
+
+export const succeed = <I, S>(
+  tag: Context.Tag<I, S>,
+  getService: (context: ResolutionContext) => Effect.Effect<S, ServiceNotAvailableError, Scope.Scope>,
+): ServiceResolver => {
+  return make((tag1, context) => {
+    if (tag1.key !== tag.key) {
+      return Effect.fail(new ServiceNotAvailableError(`Service not available: ${String(tag.key ?? tag)}`));
+    }
+    const service = getService(context);
+    return service as any;
+  });
+};
+
+/**
+ * Create a ServiceResolver from a custom resolution function.
+ */
+export const make = (
+  resolveFn: <I, S>(
+    tag: Context.Tag<I, S>,
+    context: ResolutionContext,
+  ) => Effect.Effect<S, ServiceNotAvailableError, Scope.Scope>,
+): ServiceResolver => ({
+  [ServiceResolverTypeId]: ServiceResolverTypeId,
+  resolve: resolveFn,
+});
+
+/**
+ * Create a ServiceResolver backed by a static Context.
+ * Tags present in the context are resolved; missing tags fail with ServiceNotAvailableError.
+ */
+export const fromContext = (ctx: Context.Context<any>): ServiceResolver =>
+  make((tag, context) =>
+    Effect.gen(function* () {
+      const service = Context.getOption(ctx, tag);
+      if (Option.isNone(service)) {
+        return yield* Effect.fail(new ServiceNotAvailableError(String(tag.key ?? tag)));
+      }
+      return service.value;
+    }),
+  );
+
+/**
+ * Create a ServiceResolver that resolves tags from the current Effect context.
+ * Only the specified tags are available; requests for other tags fail.
+ */
+export const fromRequirements = <const Tags extends readonly Context.Tag<any, any>[]>(
+  ...tags: Tags
+): Effect.Effect<ServiceResolver, never, Context.Tag.Identifier<Tags[number]>> =>
+  Effect.contextWith((parentCtx: Context.Context<any>) => {
+    const available = new Set(tags.map((tag) => tag.key));
+    return make((tag, context) =>
+      Effect.gen(function* () {
+        let result: Context.Context<never> = Context.empty() as Context.Context<never>;
+        if (!available.has(tag.key)) {
+          return yield* Effect.fail(new ServiceNotAvailableError(String(tag.key ?? tag)));
+        }
+        const service = Context.getOption(parentCtx, tag);
+        if (Option.isNone(service)) {
+          return yield* Effect.fail(new ServiceNotAvailableError(String(tag.key ?? tag)));
+        }
+        return service.value;
+      }),
+    );
+  });
+
+/**
+ * Like {@link fromRequirements} but returns a Layer that provides ServiceResolver.
+ */
+export const layerRequirements = <const Tags extends readonly Context.Tag<any, any>[]>(
+  ...tags: Tags
+): Layer.Layer<ServiceResolver, never, Context.Tag.Identifier<Tags[number]>> =>
+  Layer.effect(ServiceResolver, fromRequirements(...tags));
+
+/**
+ * Compose multiple resolvers left to right. Earlier resolvers take precedence:
+ * the first resolver that can satisfy a tag wins.
+ */
+export const compose = (...resolvers: readonly ServiceResolver[]): ServiceResolver =>
+  make((tag, context) =>
+    Effect.gen(function* () {
+      for (const resolver of resolvers) {
+        const single = yield* resolver.resolve(tag, context).pipe(Effect.either);
+        if (Either.isRight(single)) {
+          return single.right;
+        }
+      }
+
+      return yield* Effect.fail(new ServiceNotAvailableError(String(tag.key ?? tag)));
+    }),
+  );
+
+/**
+ * An empty resolver that fails for any requested service.
+ */
+export const empty: ServiceResolver = make((tag, context) => {
+  return Effect.fail(new ServiceNotAvailableError(String(tag.key ?? tag)));
+});