@dxos/compute 0.8.4-main.a4bbb77 → 0.8.4-main.abd8ff62ef

package/src/ServiceResolver.ts

@@ -0,0 +1,174 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Either from 'effect/Either';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+import * as Scope from 'effect/Scope';
+
+import type { DXN, SpaceId } from '@dxos/keys';
+
+import { ServiceNotAvailableError } from './errors';
+import * as Process from './Process';
+
+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)));
+});

package/src/StorageService.ts

@@ -0,0 +1,99 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import * as Pipeable from 'effect/Pipeable';
+import * as Schema from 'effect/Schema';
+
+export interface Service {
+  /** Read a value by key. Returns `None` if key does not exist. */
+  get<S extends Schema.Schema<any, string, any>>(
+    schema: S,
+    key: string,
+  ): Effect.Effect<Option.Option<Schema.Schema.Type<S>>, never, Schema.Schema.Context<S>>;
+
+  /** Write a value for the given key. */
+  set<S extends Schema.Schema<any, string, any>>(
+    schema: S,
+    key: string,
+    value: Schema.Schema.Type<S>,
+  ): Effect.Effect<void, never, Schema.Schema.Context<S>>;
+
+  /** Remove a key. */
+  delete(key: string): Effect.Effect<void>;
+
+  /** List all keys, optionally filtered by prefix. */
+  list(prefix?: string): Effect.Effect<readonly string[]>;
+
+  /** Remove all keys managed by this scoped store. */
+  clear(): Effect.Effect<void>;
+}
+
+/**
+ * Scoped key-value storage service for processes.
+ * Each process receives its own namespaced instance via the process manager.
+ * Construct a live implementation with `StorageService.layer` from `@dxos/functions-runtime`.
+ */
+export class StorageService extends Context.Tag('@dxos/functions/StorageService')<StorageService, Service>() {}
+
+export const get = Effect.serviceFunctionEffect(StorageService, (_) => _.get);
+export const set = Effect.serviceFunctionEffect(StorageService, (_) => _.set);
+export const deleteKey = Effect.serviceFunctionEffect(StorageService, (_) => _.delete);
+export const list = Effect.serviceFunctionEffect(StorageService, (_) => _.list);
+export const clear = Effect.serviceFunctionEffect(StorageService, (_) => _.clear);
+
+/**
+ * Typed key in a storage service.
+ */
+export interface Key<T> extends Pipeable.Pipeable {
+  readonly key: string;
+
+  get: Effect.Effect<Option.Option<T>, never, StorageService>;
+  set(value: T): Effect.Effect<void, never, StorageService>;
+  delete(): Effect.Effect<void, never, StorageService>;
+}
+
+/**
+ * Create a typed key in a storage service.
+ */
+export const key = <S extends Schema.Schema<any, string, any>>(schema: S, key: string): Key<Schema.Schema.Type<S>> => {
+  return {
+    key,
+    get: get(schema, key),
+    set: (value: Schema.Schema.Type<S>) => set(schema, key, value),
+    delete: () => deleteKey(key),
+    pipe(...args: any) {
+      return Pipeable.pipeArguments(this, arguments);
+    },
+  };
+};
+
+/**
+ * Typed key in a storage service with a default value.
+ */
+export interface KeyWithDefault<T, U> extends Pipeable.Pipeable {
+  readonly key: string;
+  get: Effect.Effect<T | U, never, StorageService>;
+  set(value: U): Effect.Effect<void, never, StorageService>;
+  delete(): Effect.Effect<void, never, StorageService>;
+}
+
+/**
+ * Assign a default value to a key if it is not present.
+ */
+export const withDefault =
+  <T>(getDefault: () => NoInfer<T>) =>
+  (key: Key<T>): KeyWithDefault<T, T> => {
+    return {
+      key: key.key,
+      get: key.get.pipe(Effect.map(Option.getOrElse(() => getDefault()))),
+      set: (value) => key.set(value),
+      delete: () => key.delete(),
+      pipe(...args: any) {
+        return Pipeable.pipeArguments(this, arguments);
+      },
+    };
+  };

package/src/Template.ts

@@ -0,0 +1,105 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Record from 'effect/Record';
+import * as Schema from 'effect/Schema';
+import handlebars from 'handlebars';
+
+import { Database, Ref } from '@dxos/echo';
+import type { ObjectNotFoundError } from '@dxos/echo/Err';
+import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
+import { Text } from '@dxos/schema';
+
+import { FunctionNotFoundError } from './errors';
+import * as Operation from './Operation';
+import * as OperationRegistry from './OperationRegistry';
+
+/**
+ * Template input kind determines how template variables are resolved.
+ */
+export const InputKind = Schema.Literal(
+  'value', // Literal value.
+  'pass-through',
+  'retriever',
+  'function',
+  'query',
+  'resolver',
+  'context',
+  'schema',
+);
+
+export type InputKind = Schema.Schema.Type<typeof InputKind>;
+
+/**
+ * Template input variable.
+ * E.g., {{foo}}
+ */
+export const Input = Schema.Struct({
+  name: Schema.String,
+  kind: Schema.optional(InputKind),
+  default: Schema.optional(Schema.Any),
+
+  /**
+   * Function to call if the kind is 'function'.
+   */
+  function: Schema.optional(Schema.String),
+});
+
+export type Input = Schema.Schema.Type<typeof Input>;
+
+/**
+ * Template type.
+ */
+export const Template = Schema.Struct({
+  source: Ref.Ref(Text.Text).annotations({ description: 'Handlebars template source' }),
+  inputs: Schema.optional(Schema.Array(Input)),
+});
+
+export interface Template extends Schema.Schema.Type<typeof Template> {}
+
+export const make = ({
+  id,
+  source,
+  inputs = [],
+}: { id?: string; source?: string; inputs?: Input[] } = {}): Template => ({
+  source: Ref.make(Text.make({ id, content: source })),
+  inputs,
+});
+
+/**
+ * Process Handlebars template.
+ */
+export const process = <Options extends {}>(source: string, variables: Partial<Options> = {}): string => {
+  invariant(typeof source === 'string');
+  let section = 0;
+  handlebars.registerHelper('section', () => String(++section));
+  const template = handlebars.compile(source.trim());
+  const output = template(variables);
+  return output.trim().replace(/(\n\s*){3,}/g, '\n\n');
+};
+
+export const processTemplate = (
+  template: Template,
+): Effect.Effect<string, ObjectNotFoundError | FunctionNotFoundError, OperationRegistry.Service | Operation.Service> =>
+  Effect.gen(function* () {
+    const variables = yield* Effect.forEach(template.inputs ?? [], (input) =>
+      Effect.gen(function* () {
+        if (input.kind === 'function') {
+          const fn = yield* OperationRegistry.resolve(input.function!).pipe(
+            Effect.flatten,
+            Effect.catchTag('NoSuchElementException', () => Effect.fail(new FunctionNotFoundError(input.function!))),
+          );
+          const result = yield* Operation.invoke(fn, {} as any).pipe(Effect.orDie);
+          return [input.name, result] as const;
+        } else {
+          return yield* Effect.dieMessage(`Unsupported input kind: ${input.kind}`);
+        }
+      }),
+    ).pipe(Effect.map(Record.fromEntries));
+
+    log('processTemplate', { variables });
+    return process((yield* Database.load(template.source)).content, variables);
+  });

package/src/Trace.ts

@@ -0,0 +1,231 @@
+//
+// 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 { 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 interface Event extends 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;
+};
+
+/**
+ * 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),
+
+  /**
+   * 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),
+});
+export interface Meta extends Schema.Schema.Type<typeof Meta> {}
+
+/**
+ * Envelope for a set of events.
+ */
+export const MessageData = Schema.Struct({
+  meta: Meta,
+
+  isEphemeral: Schema.Boolean,
+  events: Schema.Array(Event),
+});
+export interface MessageData extends Schema.Schema.Type<typeof MessageData> {}
+
+export const Message = MessageData.pipe(
+  Type.object({
+    typename: 'org.dxos.type.traceMessage',
+    version: '0.1.0',
+  }),
+  Annotation.IconAnnotation.set({
+    icon: 'ph--note--regular',
+    hue: 'rose',
+  }),
+);
+export interface Message extends Schema.Schema.Type<typeof Message> {}
+
+/**
+ * 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 layerNoop: Layer.Layer<TraceSink> = Layer.succeed(TraceSink, {
+  write: () => {},
+});
+
+export const layerConsole: Layer.Layer<TraceSink> = Layer.succeed(TraceSink, {
+  write: (message) => {
+    console.log(message);
+  },
+});
+
+export const testTraceService = (opts: { meta?: Meta } = {}): Layer.Layer<TraceService, never, TraceSink> =>
+  Layer.effect(
+    TraceService,
+    Effect.gen(function* () {
+      const sink = yield* TraceSink;
+      return {
+        write: (event, data) => {
+          sink.write(
+            Obj.make(Message, {
+              meta: opts.meta ?? {},
+              isEphemeral: event.isEphemeral,
+              events: [{ type: event.key, timestamp: Date.now(), 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),
+  }),
+  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),
+    /** Outcome of the operation. */
+    outcome: Schema.Literal('success', 'failure'),
+    /** Error message if the operation failed. */
+    error: Schema.optional(Schema.String),
+  }),
+  isEphemeral: false,
+});
+
+/**
+ * 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 });