@dxos/plugin-automation 0.8.4-main.c85a9c8dae → 0.8.4-main.d9fc60f731

package/src/capabilities/layer-specs.ts

@@ -0,0 +1,197 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Registry as AtomRegistry } from '@effect-atom/atom';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { OpaqueToolkit } from '@dxos/ai';
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { ClientService } from '@dxos/client';
+import { LayerSpec, OperationHandlerSet, OperationRegistry } from '@dxos/compute';
+import { ProcessManager } from '@dxos/compute-runtime';
+import { Database, Feed, Registry } from '@dxos/echo';
+import {
+  AgentService,
+  FeedTraceSink,
+  RemoteFunctionExecutionService,
+  TriggerDispatcher,
+  TriggerStateStore,
+} from '@dxos/functions-runtime';
+import { invariant } from '@dxos/invariant';
+
+//
+// Capability Module
+//
+// Contributes application- and space-affinity `Capabilities.LayerSpec` entries
+// that together replace the former monolithic `AutomationCapabilities.ComputeRuntime`.
+//
+// Specs are declared at module level; runtime state (the `Client`, contributed
+// capability lists, etc.) is resolved via Effect-level requirements rather
+// than captured from an outer scope.
+//
+
+/**
+ * Gathers contributed {@link Capabilities.OperationHandler} sets from the
+ * {@link Capability.Service} and exposes them through the
+ * {@link OperationHandlerSet.OperationHandlerProvider} tag so space-affinity
+ * specs (e.g. {@link OperationRegistrySpec}) can consume them through the
+ * normal LayerStack resolution path.
+ */
+const OperationHandlerProviderSpec = LayerSpec.make(
+  {
+    affinity: 'application',
+    requires: [Capability.Service],
+    provides: [OperationHandlerSet.OperationHandlerProvider],
+  },
+  () =>
+    Layer.unwrapEffect(
+      Effect.gen(function* () {
+        const operationHandlerSets = yield* Capability.getAll(Capabilities.OperationHandler);
+        const mergedOperationHandlers =
+          operationHandlerSets.length === 0
+            ? OperationHandlerSet.empty
+            : OperationHandlerSet.merge(...operationHandlerSets);
+        return OperationHandlerSet.provide(mergedOperationHandlers);
+      }),
+    ),
+);
+
+const RegistrySpec = LayerSpec.make(
+  {
+    affinity: 'application',
+    requires: [ClientService],
+    provides: [Registry.Service],
+  },
+  () =>
+    Layer.unwrapEffect(
+      Effect.gen(function* () {
+        const client = yield* ClientService;
+        return Layer.succeed(Registry.Service, client.graph.registry);
+      }),
+    ),
+);
+
+const OpaqueToolkitSpec = LayerSpec.make(
+  {
+    affinity: 'application',
+    requires: [Capability.Service],
+    provides: [OpaqueToolkit.OpaqueToolkitProvider],
+  },
+  () =>
+    Layer.unwrapEffect(
+      Effect.gen(function* () {
+        const capabilities = yield* Capability.Service;
+        return Layer.succeed(OpaqueToolkit.OpaqueToolkitProvider, {
+          getToolkit: () => {
+            const toolkits = capabilities.getAll(AppCapabilities.Toolkit);
+            return OpaqueToolkit.merge(...toolkits);
+          },
+        });
+      }),
+    ),
+);
+
+const AgentServiceSpec = LayerSpec.make(
+  {
+    affinity: 'application',
+    requires: [ProcessManager.ProcessManagerService],
+    provides: [AgentService.AgentService],
+  },
+  () => AgentService.layer(),
+);
+
+const OperationRegistrySpec = LayerSpec.make(
+  {
+    affinity: 'space',
+    requires: [Database.Service, OperationHandlerSet.OperationHandlerProvider],
+    provides: [OperationRegistry.Service],
+  },
+  () => OperationRegistry.layer,
+);
+
+/**
+ * In-memory trigger state. Loses state across restarts but works in both
+ * browser and CLI/Node contexts. Hosts that need durable storage should
+ * contribute a replacement LayerSpec that provides {@link TriggerStateStore}
+ * backed by a persistent `KeyValueStore` (e.g. `BrowserKeyValueStore` or
+ * `BunKeyValueStore`).
+ */
+const TriggerStateStoreSpec = LayerSpec.make(
+  {
+    affinity: 'application',
+    requires: [],
+    provides: [TriggerStateStore],
+  },
+  () => TriggerStateStore.layerMemory,
+);
+
+//
+// Space-affinity specs.
+//
+
+const FeedTraceSinkSpec = LayerSpec.make(
+  {
+    affinity: 'space',
+    requires: [Database.Service, Feed.FeedService],
+    provides: [FeedTraceSink.FeedTraceSink],
+  },
+  () => FeedTraceSink.layerLive,
+);
+
+/**
+ * Space-scoped `RemoteFunctionExecutionService`. When edge agents are enabled
+ * (`runtime.client.edgeFeatures.agents`) functions are invoked without a space
+ * binding (the edge routes them); otherwise they are scoped to the space. The
+ * config is read inside the factory — at slice-materialisation time, once
+ * `ClientService` is available — so the owning module does not need the client
+ * at activation time and can activate on `SetupProcessManager`.
+ */
+const RemoteFunctionExecutionSpec = LayerSpec.make(
+  {
+    affinity: 'space',
+    requires: [ClientService],
+    provides: [RemoteFunctionExecutionService],
+  },
+  (context) =>
+    Layer.unwrapEffect(
+      Effect.gen(function* () {
+        invariant(context.space, 'space context required for RemoteFunctionExecutionService');
+        const client = yield* ClientService;
+        const edgeAgents = client.config.get('runtime.client.edgeFeatures.agents');
+        return RemoteFunctionExecutionService.fromClient(client, edgeAgents ? undefined : context.space);
+      }),
+    ),
+);
+
+const TriggerDispatcherSpec = LayerSpec.make(
+  {
+    affinity: 'space',
+    requires: [
+      Database.Service,
+      Feed.FeedService,
+      TriggerStateStore,
+      ProcessManager.ProcessManagerService,
+      AtomRegistry.AtomRegistry,
+    ],
+    provides: [TriggerDispatcher],
+  },
+  () => TriggerDispatcher.layer({ timeControl: 'natural' }),
+);
+
+export default Capability.makeModule(() =>
+  Effect.succeed([
+    Capability.contributes(Capabilities.LayerSpec, OperationHandlerProviderSpec),
+    Capability.contributes(Capabilities.LayerSpec, RegistrySpec),
+    Capability.contributes(Capabilities.LayerSpec, OpaqueToolkitSpec),
+    Capability.contributes(Capabilities.LayerSpec, AgentServiceSpec),
+    Capability.contributes(Capabilities.LayerSpec, OperationRegistrySpec),
+    Capability.contributes(Capabilities.LayerSpec, TriggerStateStoreSpec),
+    Capability.contributes(Capabilities.LayerSpec, FeedTraceSinkSpec),
+    Capability.contributes(Capabilities.LayerSpec, TriggerDispatcherSpec),
+    Capability.contributes(Capabilities.LayerSpec, RemoteFunctionExecutionSpec),
+    Capability.contributes(Capabilities.TraceSink, ({ resolver }) => FeedTraceSink.makeRoutingSink({ resolver })),
+  ]),
+);

package/src/capabilities/node.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capability } from '@dxos/app-framework';
+import { OperationHandlerSet } from '@dxos/compute';
+
+export const AppGraphBuilder = Capability.lazy('AppGraphBuilder', () => import('./app-graph-builder'));
+export const LayerSpecs = Capability.lazy<void, Capability.Any[]>('LayerSpecs', () => import('./layer-specs'));
+export const OperationHandler = Capability.lazy<OperationHandlerSet.OperationHandlerSet>(
+  'OperationHandler',
+  () => import('./operation-handler'),
+);
+export const RegistrySync = Capability.lazy('RegistrySync', () => import('./registry-sync'));
+export const TriggerRuntimeController = Capability.lazy(
+  'TriggerRuntimeController',
+  () => import('./trigger-runtime-controller'),
+);

package/src/capabilities/operation-handler.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import type { OperationHandlerSet } from '@dxos/compute';
+
+import { AutomationOperationHandlerSet } from '#operations';
+
+export default Capability.makeModule<OperationHandlerSet.OperationHandlerSet>(
+  Effect.fnUntraced(function* () {
+    return Capability.contributes(Capabilities.OperationHandler, AutomationOperationHandlerSet);
+  }),
+);

package/src/capabilities/react-surface.tsx

@@ -0,0 +1,59 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import React from 'react';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Surface } from '@dxos/app-framework/ui';
+import { AppSurface, useActiveSpace } from '@dxos/app-toolkit/ui';
+import { getSpace } from '@dxos/react-client/echo';
+
+import { AutomationSettings, FunctionsContainer } from '#containers';
+import { meta } from '#meta';
+
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(Capabilities.ReactSurface, [
+      Surface.create({
+        id: 'spaceSettingsFunctions',
+        filter: AppSurface.literal(AppSurface.Article, `${meta.id}.space-settings-functions`),
+        component: () => {
+          const space = useActiveSpace();
+          if (!space) {
+            return null;
+          }
+
+          return <FunctionsContainer space={space} />;
+        },
+      }),
+      Surface.create({
+        id: 'spaceSettingsAutomation',
+        filter: AppSurface.literal(AppSurface.Article, `${meta.id}.space-settings-automation`),
+        component: () => {
+          const space = useActiveSpace();
+          if (!space) {
+            return null;
+          }
+
+          return <AutomationSettings space={space} />;
+        },
+      }),
+      Surface.create({
+        id: 'companion.automation',
+        filter: AppSurface.allOf(
+          AppSurface.literal(AppSurface.Article, 'automation'),
+          AppSurface.companion(AppSurface.Article),
+        ),
+        component: ({ data }) => {
+          const space = getSpace(data.companionTo);
+          if (!space) {
+            return null;
+          }
+          return <AutomationSettings space={space} object={data.companionTo} />;
+        },
+      }),
+    ]),
+  ),
+);

package/src/capabilities/registry-sync.ts

@@ -0,0 +1,110 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { Blueprint, Operation } from '@dxos/compute';
+import { log } from '@dxos/log';
+import { ClientCapabilities } from '@dxos/plugin-client';
+
+/**
+ * Syncs plugin capability contributions into `client.graph.registry`.
+ *
+ * Watches two capability atoms and imperatively adds entities to the
+ * hypergraph registry when they change:
+ * - {@link AppCapabilities.BlueprintDefinition} → instantiates each blueprint via `def.make()`.
+ * - {@link Capabilities.OperationHandler} → serializes each handler via `Operation.serialize`.
+ *
+ * Blueprint DB copies (stored in a space when a blueprint is "enabled") are treated as
+ * user forks and are not overwritten. The registry is always used as the source of truth
+ * for blueprint instructions at request time — see `formatSystemPrompt` in `@dxos/assistant`.
+ *
+ * Note: the plugin framework does not yet expose a teardown hook for capability
+ * modules (see the TODO in process-manager-capability.ts), so the subscriptions
+ * are not explicitly cancelled. They are effectively scoped to the client's lifetime.
+ */
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const client = yield* Capability.get(ClientCapabilities.Client);
+    const atomRegistry = yield* Capability.get(Capabilities.AtomRegistry);
+    const capabilityManager = yield* Capability.Service;
+
+    //
+    // Blueprint registration.
+    //
+
+    const blueprintDefinitionsAtom = capabilityManager.atom(AppCapabilities.BlueprintDefinition);
+    const prevBlueprintKeys = new Set<string>();
+
+    atomRegistry.subscribe(
+      blueprintDefinitionsAtom,
+      (definitions) => {
+        const fresh: Blueprint.Blueprint[] = [];
+        for (const def of definitions) {
+          if (!prevBlueprintKeys.has(def.key)) {
+            prevBlueprintKeys.add(def.key);
+            fresh.push(def.make());
+          }
+        }
+        if (fresh.length > 0) {
+          client.graph.registry.add(fresh);
+        }
+      },
+      { immediate: true },
+    );
+
+    //
+    // Operation registration.
+    //
+
+    const operationHandlersAtom = capabilityManager.atom(Capabilities.OperationHandler);
+    const prevOperationKeys = new Set<string>();
+
+    atomRegistry.subscribe(
+      operationHandlersAtom,
+      async (handlerSets) => {
+        try {
+          const handlers = (await Promise.all(handlerSets.map((set) => set.getHandlers()))).flat();
+          const seenKeys = new Set<string>();
+          const batch: Operation.PersistentOperation[] = [];
+          for (const handler of handlers) {
+            const key = handler.meta.key;
+            if (!key) {
+              log.warn('skipping operation handler without key');
+              continue;
+            }
+            if (seenKeys.has(key)) {
+              log('skipping duplicate operation', { key });
+              continue;
+            }
+            seenKeys.add(key);
+            if (prevOperationKeys.has(key)) {
+              continue;
+            }
+            try {
+              batch.push(Operation.serialize(handler));
+            } catch {
+              log.verbose('skipping operation with unserializable schema', { key });
+              prevOperationKeys.add(key);
+            }
+          }
+          if (batch.length > 0) {
+            client.graph.registry.add(batch);
+            for (const operation of batch) {
+              const operationKey = Operation.getKey(operation);
+              if (operationKey) {
+                prevOperationKeys.add(operationKey);
+              }
+            }
+          }
+        } catch (error) {
+          log.catch(error);
+        }
+      },
+      { immediate: true },
+    );
+  }),
+);

package/src/capabilities/trigger-runtime-controller.test.ts

@@ -0,0 +1,103 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import { describe, test } from 'vitest';
+
+import { ServiceResolver } from '@dxos/compute';
+import { Feed, Obj } from '@dxos/echo';
+import { runAndForwardErrors } from '@dxos/effect';
+import { TriggerDispatcher } from '@dxos/functions-runtime';
+import type { SpaceId } from '@dxos/keys';
+import { ClientCapabilities, ClientEvents } from '@dxos/plugin-client';
+import { ClientPlugin, initializeIdentity } from '@dxos/plugin-client/testing';
+import { createComposerTestApp } from '@dxos/plugin-testing/harness';
+
+import { AutomationPlugin } from '#plugin';
+
+/**
+ * Resolve the per-space {@link TriggerDispatcher} from the harness'
+ * process-manager runtime. The `LayerStack` caches dispatchers per
+ * `{ space }` context, so the returned instance is the same one the
+ * controller is driving.
+ */
+const getDispatcher = (harness: Awaited<ReturnType<typeof createComposerTestApp>>, spaceId: SpaceId) =>
+  harness.runPromise(
+    Effect.flatMap(TriggerDispatcher, Effect.succeed).pipe(
+      Effect.provide(ServiceResolver.provide({ space: spaceId }, TriggerDispatcher)),
+    ),
+  );
+
+describe('TriggerRuntimeController', () => {
+  test('toggles the per-space TriggerDispatcher as computeEnvironment changes', async ({ expect }) => {
+    await using harness = await createComposerTestApp({
+      plugins: [ClientPlugin({ types: [Feed.Feed] }), AutomationPlugin()],
+    });
+
+    // Creating identity also creates the personal space and emits SpacesReady,
+    // which is what gates the TriggerRuntimeController module's activation.
+    const { personalSpace } = await runAndForwardErrors(initializeIdentity(harness.get(ClientCapabilities.Client)));
+    await harness.waitForEvent(ClientEvents.SpacesReady);
+
+    const dispatcher = await getDispatcher(harness, personalSpace.id);
+
+    // Observe the dispatcher's `state` atom (the same surface the UI hook
+    // exposes through `useTriggerRuntimeControls`).
+    const observedStates: boolean[] = [];
+    const unsubscribe = harness.registry.subscribe(dispatcher.state, (state) => observedStates.push(state.enabled), {
+      immediate: true,
+    });
+    try {
+      // Default `computeEnvironment` is `local`, so the controller should
+      // start the dispatcher shortly after the space becomes ready.
+      await expect.poll(() => harness.registry.get(dispatcher.state).enabled, { timeout: 5_000 }).toBe(true);
+
+      // `disabled` → dispatcher should stop.
+      Obj.update(personalSpace.properties, (properties) => {
+        properties.computeEnvironment = 'disabled';
+      });
+      await expect.poll(() => harness.registry.get(dispatcher.state).enabled, { timeout: 5_000 }).toBe(false);
+
+      // Back to `local` → dispatcher should start again.
+      Obj.update(personalSpace.properties, (properties) => {
+        properties.computeEnvironment = 'local';
+      });
+      await expect.poll(() => harness.registry.get(dispatcher.state).enabled, { timeout: 5_000 }).toBe(true);
+
+      // `edge` → dispatcher should stop (triggers run on the edge instead).
+      Obj.update(personalSpace.properties, (properties) => {
+        properties.computeEnvironment = 'edge';
+      });
+      await expect.poll(() => harness.registry.get(dispatcher.state).enabled, { timeout: 5_000 }).toBe(false);
+
+      // The atom subscription should have witnessed every transition.
+      expect(observedStates).toEqual(expect.arrayContaining([true, false, true, false]));
+    } finally {
+      unsubscribe();
+    }
+  });
+
+  test('does not re-issue start when computeEnvironment is reasserted to the same value', async ({ expect }) => {
+    await using harness = await createComposerTestApp({
+      plugins: [ClientPlugin({ types: [Feed.Feed] }), AutomationPlugin()],
+    });
+
+    const { personalSpace } = await runAndForwardErrors(initializeIdentity(harness.get(ClientCapabilities.Client)));
+    await harness.waitForEvent(ClientEvents.SpacesReady);
+
+    const dispatcher = await getDispatcher(harness, personalSpace.id);
+
+    await expect.poll(() => harness.registry.get(dispatcher.state).enabled, { timeout: 5_000 }).toBe(true);
+
+    // Writing the same `local` value should be a no-op: the controller
+    // dedupes via its `lastEnvironment` tracker so the dispatcher stays
+    // running without an intervening stop/start flicker.
+    Obj.update(personalSpace.properties, (properties) => {
+      properties.computeEnvironment = 'local';
+    });
+    // Give any spurious transition a chance to land before we check.
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    expect(harness.registry.get(dispatcher.state).enabled).toBe(true);
+  });
+});

package/src/capabilities/trigger-runtime-controller.ts

@@ -0,0 +1,126 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Fiber from 'effect/Fiber';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { type ComputeEnvironment } from '@dxos/client-protocol';
+import { ServiceResolver } from '@dxos/compute';
+import { Obj } from '@dxos/echo';
+import { TriggerDispatcher } from '@dxos/functions-runtime';
+import { type SpaceId } from '@dxos/keys';
+import { log } from '@dxos/log';
+import { ClientCapabilities } from '@dxos/plugin-client';
+import { type Space } from '@dxos/react-client/echo';
+
+//
+// Capability Module
+//
+// Watches `space.properties.computeEnvironment` for every space and toggles
+// the per-space {@link TriggerDispatcher} accordingly:
+//
+//   - `local`              → `dispatcher.start()`
+//   - `edge` / `disabled`  → `dispatcher.stop()`
+//
+// Replaces the in-line watcher that used to live inside the removed
+// `compute-runtime.ts` per-space layer. The dispatcher itself is now
+// contributed unconditionally via `TriggerDispatcherSpec` in `layer-specs.ts`,
+// so this capability is only responsible for driving its lifecycle.
+//
+
+/** Trigger execution location the dispatcher should run locally. */
+const LOCAL_ENVIRONMENT: ComputeEnvironment = 'local';
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const client = yield* Capability.get(ClientCapabilities.Client);
+    const runtime = yield* Capability.get(Capabilities.ProcessManagerRuntime);
+
+    /** Per-space property-subscription unsubscribe, last-seen environment, and in-flight transition fiber. */
+    type Tracker = {
+      unsubscribe: () => void;
+      lastEnvironment?: ComputeEnvironment;
+      inFlight?: Fiber.RuntimeFiber<unknown, unknown>;
+    };
+    const trackers = new Map<SpaceId, Tracker>();
+
+    /**
+     * Resolve the per-space `TriggerDispatcher` from the process-manager
+     * runtime and invoke `start()` / `stop()` according to the requested
+     * environment. Returns a fiber so the caller can cancel a pending
+     * transition when a new one supersedes it.
+     */
+    const transition = (spaceId: SpaceId, environment: ComputeEnvironment) =>
+      runtime.runFork(
+        Effect.gen(function* () {
+          const dispatcher = yield* TriggerDispatcher;
+          yield* environment === LOCAL_ENVIRONMENT ? dispatcher.start() : dispatcher.stop();
+        }).pipe(
+          Effect.provide(ServiceResolver.provide({ space: spaceId }, TriggerDispatcher)),
+          Effect.tapErrorCause((cause) =>
+            Effect.sync(() => log.warn('trigger dispatcher transition failed', { spaceId, environment, cause })),
+          ),
+        ),
+      );
+
+    const apply = (tracker: Tracker, spaceId: SpaceId, environment: ComputeEnvironment): void => {
+      if (tracker.lastEnvironment === environment) {
+        return;
+      }
+      tracker.lastEnvironment = environment;
+      if (tracker.inFlight) {
+        runtime.runFork(Fiber.interrupt(tracker.inFlight));
+      }
+      tracker.inFlight = transition(spaceId, environment);
+    };
+
+    const install = (space: Space): void => {
+      if (trackers.has(space.id)) {
+        return;
+      }
+      // Reserve the slot synchronously so concurrent `client.spaces.subscribe`
+      // notifications (e.g. spaces array churn while we await readiness) don't
+      // wire a second subscriber for the same space.
+      const tracker: Tracker = { unsubscribe: () => {} };
+      trackers.set(space.id, tracker);
+
+      void space
+        .waitUntilReady()
+        .then(() => {
+          // The capability could have been torn down between `set` and the
+          // promise resolving; bail out without subscribing in that case.
+          if (trackers.get(space.id) !== tracker) {
+            return;
+          }
+          const readEnvironment = (): ComputeEnvironment => space.properties.computeEnvironment ?? LOCAL_ENVIRONMENT;
+          tracker.unsubscribe = Obj.subscribe(space.properties, () => apply(tracker, space.id, readEnvironment()));
+          apply(tracker, space.id, readEnvironment());
+        })
+        .catch((err) => log.catch(err));
+    };
+
+    const installAll = (spaces: readonly Space[]): void => {
+      for (const space of spaces) {
+        install(space);
+      }
+    };
+
+    const spacesSubscription = client.spaces.subscribe(installAll);
+    installAll(client.spaces.get());
+
+    return Capability.contributes(Capabilities.Null, null, () =>
+      Effect.sync(() => {
+        spacesSubscription.unsubscribe();
+        for (const tracker of trackers.values()) {
+          tracker.unsubscribe();
+          if (tracker.inFlight) {
+            runtime.runFork(Fiber.interrupt(tracker.inFlight));
+          }
+        }
+        trackers.clear();
+      }),
+    );
+  }),
+);