@dxos/plugin-routine 0.0.0

package/dx.config.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Config2 } from '@dxos/app-framework/config';
+import { trim } from '@dxos/util';
+
+export default Config2.make({
+  plugin: {
+    key: 'org.dxos.plugin.routine',
+    name: 'Routine',
+    author: 'DXOS',
+    description: trim`
+      Event-driven workflow automation engine for DXOS Composer.
+      A Routine pairs a trigger ("when" — a timer schedule or an incoming feed) with an action
+      ("then" — a persistent compute operation and instructions), enabling automated pipelines that
+      react to changes in real time without manual intervention.
+
+      Routines are configured in their own article and surfaced on a per-object "Routines" companion
+      that lists the routines connected to each object. A per-space TriggerDispatcher manages
+      execution: running locally in the browser when computeEnvironment is "local", or delegating to
+      the DXOS edge for server-side reliability; the space settings page chooses the runtime location.
+
+      Operation handlers and skills contributed by any plugin in the application are
+      automatically merged and made available to every space's OperationRegistry, so new
+      capabilities registered by other plugins become instantly invocable from routines.
+    `,
+    icon: { key: 'ph--atom--regular' },
+    source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-routine',
+    spec: 'PLUGIN.mdl',
+    tags: ['system'],
+  },
+});

package/package.json

@@ -0,0 +1,196 @@
+{
+  "name": "@dxos/plugin-routine",
+  "version": "0.0.0",
+  "description": "Prompt chain plugin",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "FSL-1.1-Apache-2.0",
+  "author": "DXOS.org",
+  "sideEffects": true,
+  "type": "module",
+  "imports": {
+    "#capabilities": {
+      "source": {
+        "node": "./src/capabilities/node.ts",
+        "default": "./src/capabilities/index.ts"
+      },
+      "types": "./dist/types/src/capabilities/index.d.ts",
+      "node": "./dist/lib/neutral/capabilities/node.mjs",
+      "default": "./dist/lib/neutral/capabilities/index.mjs"
+    },
+    "#components": {
+      "source": "./src/components/index.ts",
+      "types": "./dist/types/src/components/index.d.ts",
+      "default": "./dist/lib/neutral/components/index.mjs"
+    },
+    "#containers": {
+      "source": "./src/containers/index.ts",
+      "types": "./dist/types/src/containers/index.d.ts",
+      "default": "./dist/lib/neutral/containers/index.mjs"
+    },
+    "#hooks": {
+      "source": "./src/hooks/index.ts",
+      "types": "./dist/types/src/hooks/index.d.ts",
+      "default": "./dist/lib/neutral/hooks/index.mjs"
+    },
+    "#meta": {
+      "source": "./src/meta.ts",
+      "types": "./dist/types/src/meta.d.ts",
+      "default": "./dist/lib/neutral/meta.mjs"
+    },
+    "#operations": {
+      "source": "./src/operations/index.ts",
+      "types": "./dist/types/src/operations/index.d.ts",
+      "default": "./dist/lib/neutral/operations/index.mjs"
+    },
+    "#plugin": {
+      "source": {
+        "workerd": "./src/RoutinePlugin.workerd.ts",
+        "node": "./src/RoutinePlugin.node.ts",
+        "default": "./src/RoutinePlugin.tsx"
+      },
+      "types": "./dist/types/src/RoutinePlugin.d.ts",
+      "workerd": "./dist/lib/neutral/RoutinePlugin.workerd.mjs",
+      "node": "./dist/lib/neutral/RoutinePlugin.node.mjs",
+      "default": "./dist/lib/neutral/RoutinePlugin.mjs"
+    },
+    "#testing": "./src/testing/index.ts",
+    "#translations": {
+      "source": "./src/translations.ts",
+      "types": "./dist/types/src/translations.d.ts",
+      "default": "./dist/lib/neutral/translations.mjs"
+    },
+    "#types": {
+      "source": "./src/types/index.ts",
+      "types": "./dist/types/src/types/index.d.ts",
+      "default": "./dist/lib/neutral/types/index.mjs"
+    }
+  },
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/types/src/index.d.ts",
+      "default": "./dist/lib/neutral/index.mjs"
+    },
+    "./assets/PLUGIN.mdl": "./PLUGIN.mdl",
+    "./components": {
+      "source": "./src/components/index.ts",
+      "types": "./dist/types/src/components/index.d.ts",
+      "default": "./dist/lib/neutral/components/index.mjs"
+    },
+    "./hooks": {
+      "source": "./src/hooks/index.ts",
+      "types": "./dist/types/src/hooks/index.d.ts",
+      "default": "./dist/lib/neutral/hooks/index.mjs"
+    },
+    "./plugin": {
+      "source": "./src/plugin.ts",
+      "types": "./dist/types/src/plugin.d.ts",
+      "default": "./dist/lib/neutral/plugin.mjs"
+    },
+    "./testing": {
+      "source": "./src/testing.ts",
+      "types": "./dist/types/src/testing.d.ts",
+      "default": "./dist/lib/neutral/testing.mjs"
+    },
+    "./translations": {
+      "source": "./src/translations.ts",
+      "types": "./dist/types/src/translations.d.ts",
+      "default": "./dist/lib/neutral/translations.mjs"
+    },
+    "./types": {
+      "source": "./src/types/index.ts",
+      "types": "./dist/types/src/types/index.d.ts",
+      "default": "./dist/lib/neutral/types/index.mjs"
+    }
+  },
+  "types": "dist/types/src/index.d.ts",
+  "files": [
+    "assets",
+    "dist",
+    "dx.config.ts",
+    "src",
+    "PLUGIN.mdl"
+  ],
+  "dependencies": {
+    "@codemirror/autocomplete": "catalog:",
+    "@codemirror/language": "catalog:",
+    "@codemirror/state": "catalog:",
+    "@codemirror/view": "catalog:",
+    "@dxos/ai": "workspace:*",
+    "@dxos/app-framework": "workspace:*",
+    "@dxos/app-toolkit": "workspace:*",
+    "@dxos/assistant-toolkit": "workspace:*",
+    "@dxos/cli-util": "workspace:*",
+    "@dxos/client": "workspace:*",
+    "@dxos/client-protocol": "workspace:*",
+    "@dxos/compute": "workspace:*",
+    "@dxos/compute-runtime": "workspace:*",
+    "@dxos/conductor": "workspace:*",
+    "@dxos/context": "workspace:*",
+    "@dxos/echo": "workspace:*",
+    "@dxos/echo-doc": "workspace:*",
+    "@dxos/echo-react": "workspace:*",
+    "@dxos/edge-client": "workspace:*",
+    "@dxos/effect": "workspace:*",
+    "@dxos/functions-runtime": "workspace:*",
+    "@dxos/invariant": "workspace:*",
+    "@dxos/keys": "workspace:*",
+    "@dxos/log": "workspace:*",
+    "@dxos/plugin-client": "workspace:*",
+    "@dxos/plugin-graph": "workspace:*",
+    "@dxos/plugin-markdown": "workspace:*",
+    "@dxos/plugin-space": "workspace:*",
+    "@dxos/random": "workspace:*",
+    "@dxos/react-client": "workspace:*",
+    "@dxos/react-ui-attention": "workspace:*",
+    "@dxos/react-ui-components": "workspace:*",
+    "@dxos/react-ui-editor": "workspace:*",
+    "@dxos/react-ui-form": "workspace:*",
+    "@dxos/react-ui-list": "workspace:*",
+    "@dxos/react-ui-menu": "workspace:*",
+    "@dxos/react-ui-search": "workspace:*",
+    "@dxos/react-ui-syntax-highlighter": "workspace:*",
+    "@dxos/schema": "workspace:*",
+    "@dxos/types": "workspace:*",
+    "@dxos/ui": "workspace:*",
+    "@dxos/ui-editor": "workspace:*",
+    "@dxos/util": "workspace:*",
+    "@effect-atom/atom": "catalog:",
+    "@effect/cli": "catalog:",
+    "@effect/printer-ansi": "catalog:",
+    "@radix-ui/react-compose-refs": "catalog:",
+    "cronstrue": "catalog:"
+  },
+  "devDependencies": {
+    "@dxos/assistant": "workspace:*",
+    "@dxos/plugin-testing": "workspace:*",
+    "@dxos/react-ui": "workspace:*",
+    "@dxos/storybook-utils": "workspace:*",
+    "@dxos/ui-theme": "workspace:*",
+    "@effect-atom/atom-react": "catalog:",
+    "@effect/platform": "catalog:",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
+    "effect": "catalog:",
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "vite": "catalog:"
+  },
+  "peerDependencies": {
+    "@dxos/react-ui": "workspace:*",
+    "@dxos/ui-theme": "workspace:*",
+    "@effect-atom/atom-react": "catalog:",
+    "@effect/platform": "catalog:",
+    "effect": "catalog:",
+    "react": "catalog:",
+    "react-dom": "catalog:"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/RoutinePlugin.node.ts

@@ -0,0 +1,48 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { ActivationEvent, ActivationEvents, Plugin } from '@dxos/app-framework';
+import { AppActivationEvents, AppPlugin } from '@dxos/app-toolkit';
+import { Operation, Trace, Trigger } from '@dxos/compute';
+import { ClientEvents } from '@dxos/plugin-client';
+
+import {
+  AppGraphBuilder,
+  LayerSpecs,
+  OperationHandler,
+  RegistrySync,
+  Templates,
+  TriggerRuntimeController,
+} from '#capabilities';
+import { meta } from '#meta';
+import { Routine } from '#types';
+
+import { trigger } from './commands';
+
+export const RoutinePlugin = Plugin.define(meta).pipe(
+  AppPlugin.addAppGraphModule({ activate: AppGraphBuilder }),
+  AppPlugin.addCommandModule({ commands: [trigger] }),
+  AppPlugin.addOperationHandlerModule({ activate: OperationHandler }),
+  AppPlugin.addSchemaModule({
+    schema: [Routine.Routine, Operation.PersistentOperation, Trigger.Trigger, Trace.Message],
+  }),
+  // CreateRoutine (in OperationHandler) resolves RoutineCapabilities.Template, so the template
+  // provider must be present wherever the handler is exported.
+  Plugin.addModule({ id: 'automation-templates', activatesOn: AppActivationEvents.SetupSchema, activate: Templates }),
+  Plugin.addModule({
+    activatesOn: ActivationEvents.SetupProcessManager,
+    activate: LayerSpecs,
+  }),
+  Plugin.addModule({
+    activatesOn: ClientEvents.ClientReady,
+    activate: RegistrySync,
+  }),
+  Plugin.addModule({
+    activatesOn: ActivationEvent.allOf(ActivationEvents.ProcessManagerReady, ClientEvents.SpacesReady),
+    activate: TriggerRuntimeController,
+  }),
+  Plugin.make,
+);
+
+export default RoutinePlugin;

package/src/RoutinePlugin.test.ts

@@ -0,0 +1,27 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { ClientPlugin } from '@dxos/plugin-client/plugin';
+import { createComposerTestApp } from '@dxos/plugin-testing/harness';
+
+import { RoutinePlugin } from '#plugin';
+
+import { meta } from './meta';
+
+const moduleId = (name: string) => `${meta.profile.key}.module.${name}`;
+
+describe('RoutinePlugin', () => {
+  test('modules activate on the expected events', async ({ expect }) => {
+    await using harness = await createComposerTestApp({
+      plugins: [ClientPlugin({}), RoutinePlugin()],
+    });
+
+    // After autoStart: AppGraphBuilder, schema, OperationHandler all auto-cascade.
+    expect(harness.manager.getActive()).toEqual(
+      expect.arrayContaining([moduleId('AppGraphBuilder'), moduleId('schema'), moduleId('OperationHandler')]),
+    );
+  });
+});

package/src/RoutinePlugin.tsx

@@ -0,0 +1,58 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { ActivationEvent, ActivationEvents, Plugin } from '@dxos/app-framework';
+import { AppActivationEvents, AppPlugin } from '@dxos/app-toolkit';
+import { Instructions, Operation, Trace, Trigger } from '@dxos/compute';
+import { ClientEvents } from '@dxos/plugin-client';
+
+import {
+  AppGraphBuilder,
+  CreateObject,
+  LayerSpecs,
+  NavigationResolver,
+  OperationHandler,
+  ReactSurface,
+  RegistrySync,
+  Templates,
+  TriggerRuntimeController,
+} from '#capabilities';
+import { meta } from '#meta';
+import { translations } from '#translations';
+import { Routine } from '#types';
+
+// eslint-disable-next-line import/no-relative-packages
+import pluginSpec from '../PLUGIN.mdl?raw';
+
+export const RoutinePlugin = Plugin.define(meta).pipe(
+  AppPlugin.addAppGraphModule({ activate: AppGraphBuilder }),
+  AppPlugin.addCreateObjectModule({ activate: CreateObject }),
+  AppPlugin.addNavigationResolverModule({ activatesOn: ClientEvents.ClientReady, activate: NavigationResolver }),
+  AppPlugin.addOperationHandlerModule({ activate: OperationHandler }),
+  AppPlugin.addPluginAssetModule({
+    asset: { pluginId: meta.profile.key, path: 'PLUGIN.mdl', content: pluginSpec, mimeType: 'application/x-mdl' },
+  }),
+  AppPlugin.addSchemaModule({
+    schema: [Routine.Routine, Operation.PersistentOperation, Instructions.Instructions, Trigger.Trigger, Trace.Message],
+  }),
+  AppPlugin.addSurfaceModule({ activate: ReactSurface }),
+  AppPlugin.addTranslationsModule({ translations }),
+  Plugin.addModule({
+    activatesOn: ClientEvents.ClientReady,
+    firesBeforeActivation: [ActivationEvents.SetupProcessManager],
+    activate: LayerSpecs,
+  }),
+  Plugin.addModule({
+    activatesOn: ClientEvents.ClientReady,
+    activate: RegistrySync,
+  }),
+  Plugin.addModule({ activatesOn: AppActivationEvents.SetupSchema, activate: Templates }),
+  Plugin.addModule({
+    activatesOn: ActivationEvent.allOf(ActivationEvents.ProcessManagerReady, ClientEvents.SpacesReady),
+    activate: TriggerRuntimeController,
+  }),
+  Plugin.make,
+);
+
+export default RoutinePlugin;

package/src/RoutinePlugin.workerd.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+import { AppActivationEvents, AppPlugin } from '@dxos/app-toolkit';
+import { Operation, Trace, Trigger } from '@dxos/compute';
+
+import { OperationHandler, Templates } from '#capabilities';
+import { meta } from '#meta';
+import { Routine } from '#types';
+
+export const RoutinePlugin = Plugin.define(meta).pipe(
+  AppPlugin.addOperationHandlerModule({ activate: OperationHandler }),
+  AppPlugin.addSchemaModule({
+    schema: [Routine.Routine, Operation.PersistentOperation, Trigger.Trigger, Trace.Message],
+  }),
+  // CreateRoutine (in OperationHandler) resolves RoutineCapabilities.Template, so the template
+  // provider must be present wherever the handler is exported.
+  Plugin.addModule({ id: 'automation-templates', activatesOn: AppActivationEvents.SetupSchema, activate: Templates }),
+  Plugin.make,
+);
+
+export default RoutinePlugin;

package/src/capabilities/app-graph-builder.ts

@@ -0,0 +1,80 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { AppCapabilities, AppNode, AppNodeMatcher, Paths, TypeSection } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/compute';
+import { Type } from '@dxos/echo';
+import { GraphBuilder, NodeMatcher } from '@dxos/plugin-graph';
+import { SETTINGS_SECTION_TYPE, SpaceOperation } from '@dxos/plugin-space';
+import { linkedSegment } from '@dxos/react-ui-attention';
+import { Position } from '@dxos/util';
+
+import { meta } from '#meta';
+import { Routine } from '#types';
+
+import { getRoutinesPath } from '../paths';
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const extensions = yield* Effect.all([
+      TypeSection.createTypeSectionExtension(Routine.Routine, {
+        match: AppNodeMatcher.whenNavTreeGroup(Paths.GroupTypes.ai),
+        createObject: (space) =>
+          Operation.invoke(SpaceOperation.OpenCreateObject, {
+            target: space.db,
+            typename: Type.getTypename(Routine.Routine),
+            targetNodeId: getRoutinesPath(space.db.spaceId),
+          }),
+      }),
+      GraphBuilder.createExtension({
+        id: 'spaceSettingsAutomation',
+        match: NodeMatcher.whenNodeType(SETTINGS_SECTION_TYPE),
+        connector: () => {
+          return Effect.succeed([
+            AppNode.makeSettingsPanel({
+              id: 'routines',
+              type: `${meta.profile.key}.space-settings-automation`,
+              label: ['automation-panel.label', { ns: meta.profile.key }],
+              icon: 'ph--lightning--regular',
+              iconHue: 'emerald',
+              position: Position.last,
+            }),
+          ]);
+        },
+      }),
+      GraphBuilder.createExtension({
+        id: 'automationCompanion',
+        match: NodeMatcher.whenEchoObjectMatches,
+        connector: () =>
+          Effect.succeed([
+            AppNode.makeCompanion({
+              id: linkedSegment('automation'),
+              label: ['automation-companion.label', { ns: meta.profile.key }],
+              icon: 'ph--lightning--regular',
+              data: 'automation',
+              position: Position.last,
+            }),
+          ]),
+      }),
+      GraphBuilder.createTypeExtension({
+        id: 'routineRuns',
+        type: Routine.Routine,
+        connector: () =>
+          Effect.succeed([
+            AppNode.makeCompanion({
+              id: 'runs',
+              label: ['routine-runs.label', { ns: meta.profile.key }],
+              icon: 'ph--clock-countdown--regular',
+              data: 'runs',
+            }),
+          ]),
+      }),
+    ]);
+
+    return Capability.contributes(AppCapabilities.AppGraphBuilder, extensions);
+  }),
+);

package/src/capabilities/create-object.test.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { defaultTemplates } from '../templates';
+
+// The full create-object path is exercised by the app e2e (the UI plugin variant can't boot in the headless
+// node harness); this asserts the Blank template the flow depends on.
+describe('Routine create templates', () => {
+  test('ships a Blank no-op template', ({ expect }) => {
+    const blank = defaultTemplates.find((template) => template.id === 'org.dxos.routine.blank');
+    expect(blank).toBeDefined();
+    expect(blank!.label).toBe('Blank');
+    expect(typeof blank!.scaffold).toBe('function');
+  });
+});

package/src/capabilities/create-object.ts

@@ -0,0 +1,26 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+import { Type } from '@dxos/echo';
+import { SpaceCapabilities } from '@dxos/plugin-space';
+
+import { CreateRoutinePanel } from '#components';
+import { Routine, RoutineOperation } from '#types';
+
+type CreateOptions = Parameters<SpaceCapabilities.CreateObjectEntry['createObject']>[1];
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    return Capability.contributes(SpaceCapabilities.CreateObjectEntry, {
+      id: Type.getTypename(Routine.Routine),
+      customPanel: CreateRoutinePanel,
+      createObject: ({ name, templateId }: { name?: string; templateId: string }, options: CreateOptions) =>
+        Operation.invoke(RoutineOperation.CreateRoutine, { db: options.db, templateId, name }),
+    });
+  }),
+);

package/src/capabilities/index.ts

@@ -0,0 +1,22 @@
+//
+// 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 NavigationResolver = Capability.lazy('NavigationResolver', () => import('./navigation-resolver'));
+export const CreateObject = Capability.lazy('CreateObject', () => import('./create-object'));
+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 ReactSurface = Capability.lazy('ReactSurface', () => import('./react-surface'));
+export const RegistrySync = Capability.lazy('RegistrySync', () => import('./registry-sync'));
+export const Templates = Capability.lazy('Templates', () => import('./templates'));
+export const TriggerRuntimeController = Capability.lazy(
+  'TriggerRuntimeController',
+  () => import('./trigger-runtime-controller'),
+);