@dxos/plugin-automation 0.8.4-main.e8ec1fe → 0.8.4-main.effb148878

package/src/capabilities/layer-specs.ts

@@ -0,0 +1,230 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Registry } 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 { Blueprint, LayerSpec, OperationHandlerSet, OperationRegistry } from '@dxos/compute';
+import { ProcessManager } from '@dxos/compute-runtime';
+import { Database, Feed } from '@dxos/echo';
+import {
+  AgentService,
+  FeedTraceSink,
+  RemoteFunctionExecutionService,
+  TriggerDispatcher,
+  TriggerStateStore,
+} from '@dxos/functions-runtime';
+import { invariant } from '@dxos/invariant';
+import { ClientCapabilities } from '@dxos/plugin-client';
+
+//
+// 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.
+//
+
+/**
+ * Default application-affinity `RemoteFunctionExecutionService`. Space specs
+ * (see {@link RemoteFunctionExecutionOverrideSpec}) can override this with a
+ * space-scoped client.
+ */
+const RemoteFunctionExecutionSpec = LayerSpec.make(
+  {
+    affinity: 'application',
+    requires: [ClientService],
+    provides: [RemoteFunctionExecutionService],
+  },
+  () =>
+    Layer.unwrapEffect(
+      Effect.gen(function* () {
+        const client = yield* ClientService;
+        return RemoteFunctionExecutionService.fromClient(client);
+      }),
+    ),
+);
+
+/**
+ * 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 BlueprintRegistrySpec = LayerSpec.make(
+  {
+    affinity: 'application',
+    requires: [Capability.Service],
+    provides: [Blueprint.RegistryService],
+  },
+  () =>
+    Layer.unwrapEffect(
+      Effect.gen(function* () {
+        const capabilities = yield* Capability.Service;
+        const blueprints = capabilities
+          .getAll(AppCapabilities.BlueprintDefinition)
+          .flatMap((blueprint) => blueprint.make());
+        return Layer.succeed(Blueprint.RegistryService, new Blueprint.Registry(blueprints));
+      }),
+    ),
+);
+
+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 override of {@link RemoteFunctionExecutionService}. Activated
+ * only when the client's `runtime.client.edgeFeatures.agents` config is set;
+ * falls back to the application-level spec otherwise.
+ */
+const RemoteFunctionExecutionOverrideSpec = LayerSpec.make(
+  {
+    affinity: 'space',
+    requires: [ClientService],
+    provides: [RemoteFunctionExecutionService],
+  },
+  (context) =>
+    Layer.unwrapEffect(
+      Effect.gen(function* () {
+        invariant(context.space, 'space context required for RemoteFunctionExecutionService override');
+        const client = yield* ClientService;
+        return RemoteFunctionExecutionService.fromClient(client, context.space);
+      }),
+    ),
+);
+
+const TriggerDispatcherSpec = LayerSpec.make(
+  {
+    affinity: 'space',
+    requires: [
+      Database.Service,
+      Feed.FeedService,
+      TriggerStateStore,
+      ProcessManager.ProcessManagerService,
+      Registry.AtomRegistry,
+    ],
+    provides: [TriggerDispatcher],
+  },
+  () => TriggerDispatcher.layer({ timeControl: 'natural' }),
+);
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const client = yield* Capability.get(ClientCapabilities.Client);
+
+    const contributions: Capability.Any[] = [
+      Capability.contributes(Capabilities.LayerSpec, OperationHandlerProviderSpec),
+      Capability.contributes(Capabilities.LayerSpec, BlueprintRegistrySpec),
+      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.TraceSink, ({ resolver }) => FeedTraceSink.makeRoutingSink({ resolver })),
+      // Edge-mode override is conditional on runtime config, so it stays in the
+      // activation block.
+      Capability.contributes(
+        Capabilities.LayerSpec,
+        client.config.get('runtime.client.edgeFeatures.agents')
+          ? RemoteFunctionExecutionSpec
+          : RemoteFunctionExecutionOverrideSpec,
+      ),
+    ];
+
+    return contributions;
+  }),
+);

package/src/capabilities/node.ts

@@ -0,0 +1,17 @@
+//
+// 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 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

@@ -2,55 +2,58 @@
 // Copyright 2025 DXOS.org
 //
 
+import * as Effect from 'effect/Effect';
 import React from 'react';
 
-import { Capabilities, contributes, createSurface } from '@dxos/app-framework';
-import { useLayout } from '@dxos/app-framework/react';
-import { Obj } from '@dxos/echo';
-import { getSpace, parseId, useSpace } from '@dxos/react-client/echo';
+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 '../components';
-import { meta } from '../meta';
+import { AutomationSettings, FunctionsContainer } from '#containers';
+import { meta } from '#meta';
 
-export default () =>
-  contributes(Capabilities.ReactSurface, [
-    createSurface({
-      id: `${meta.id}/space-settings-functions`,
-      role: 'article',
-      filter: (data): data is { subject: string } => data.subject === `${meta.id}/space-settings-functions`,
-      component: () => {
-        const layout = useLayout();
-        const { spaceId } = parseId(layout.workspace);
-        const space = useSpace(spaceId);
-        if (!space) {
-          return null;
-        }
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(Capabilities.ReactSurface, [
+      Surface.create({
+        id: 'space-settings-functions',
+        filter: AppSurface.literal(AppSurface.Article, `${meta.id}.space-settings-functions`),
+        component: () => {
+          const space = useActiveSpace();
+          if (!space) {
+            return null;
+          }
 
-        return <FunctionsContainer space={space} />;
-      },
-    }),
-    createSurface({
-      id: `${meta.id}/space-settings-automation`,
-      role: 'article',
-      filter: (data): data is { subject: string } => data.subject === `${meta.id}/space-settings-automation`,
-      component: () => {
-        const layout = useLayout();
-        const { spaceId } = parseId(layout.workspace);
-        const space = useSpace(spaceId);
-        if (!space) {
-          return null;
-        }
+          return <FunctionsContainer space={space} />;
+        },
+      }),
+      Surface.create({
+        id: 'space-settings-automation',
+        filter: AppSurface.literal(AppSurface.Article, `${meta.id}.space-settings-automation`),
+        component: () => {
+          const space = useActiveSpace();
+          if (!space) {
+            return null;
+          }
 
-        return <AutomationSettings space={space} />;
-      },
-    }),
-    createSurface({
-      id: `${meta.id}/companion/automation`,
-      role: 'article',
-      filter: (data): data is { companionTo: Obj.Any; subject: 'automation' } =>
-        Obj.isObject(data.companionTo) && data.subject === 'automation',
-      component: ({ data }) => {
-        return <AutomationSettings space={getSpace(data.companionTo)!} object={data.companionTo} />;
-      },
-    }),
-  ]);
+          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/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();
+      }),
+    );
+  }),
+);

package/src/commands/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './trigger';

package/src/commands/trigger/create/index.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Command from '@effect/cli/Command';
+
+import { queue } from './queue';
+import { subscription } from './subscription';
+import { timer } from './timer';
+
+export const create = Command.make('create').pipe(
+  Command.withDescription('Create a trigger.'),
+  Command.withSubcommands([subscription, timer, queue]),
+);