@dxos/plugin-automation 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/containers/AutomationCompanion/AutomationCompanion.tsx

@@ -0,0 +1,183 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { useCallback, useMemo, useRef, useState } from 'react';
+
+import { useCapabilities, useOperationInvoker } from '@dxos/app-framework/ui';
+import { type Database, Filter, Obj, Type } from '@dxos/echo';
+import { useQuery } from '@dxos/react-client/echo';
+import { DropdownMenu, Icon, Tooltip, useTranslation } from '@dxos/react-ui';
+import { Accordion } from '@dxos/react-ui-list';
+
+import { meta } from '#meta';
+import { Automation, AutomationCapabilities, AutomationOperation } from '#types';
+
+import { AutomationInlineForm } from '../../containers/AutomationArticle';
+import { connectedAutomationsQuery } from '../../util/automations-for-object';
+
+export type AutomationCompanionProps = {
+  db: Database.Database;
+  object: Obj.Unknown;
+};
+
+/** Association state of a row relative to the companion's object. */
+type Status = 'associated' | 'pending' | 'detached';
+
+/**
+ * Renders the automations connected to an object as an accordion (see `useConnectedAutomations` for the
+ * session-stable list it draws from), flagging non-associated rows with a warning badge. New automations are
+ * created from a template dropdown (no dialog).
+ */
+export const AutomationCompanion = ({ db, object }: AutomationCompanionProps) => {
+  const { t } = useTranslation(meta.id);
+  const templates = useCapabilities(AutomationCapabilities.Template);
+  // Only offer templates applicable to this companion's subject (e.g. a CRM template needs a Mailbox).
+  const applicableTemplates = useMemo(
+    () => templates.filter((template) => template.appliesTo?.(object) ?? true),
+    [templates, object],
+  );
+  const { items, statusFor, open, setOpen, handleCreate } = useConnectedAutomations(db, object);
+
+  return (
+    <div className='flex flex-col'>
+      {items.length === 0 ? (
+        <p className='text-sm text-description p-2'>{t('no-automations.message')}</p>
+      ) : (
+        <Accordion.Root<Automation.Automation> items={items} value={open} onValueChange={setOpen}>
+          {({ items }) => (
+            <div className='flex flex-col divide-y divide-separator'>
+              {items.map((automation) => {
+                const status = statusFor(automation.id);
+                return (
+                  <Accordion.Item key={automation.id} item={automation}>
+                    <Accordion.ItemHeader>
+                      <Icon icon='ph--lightning--regular' size={4} classNames='mr-2 shrink-0' />
+                      <span className='flex-1 truncate'>
+                        {Obj.getLabel(automation) ??
+                          t('object-name.placeholder', { ns: Type.getTypename(Automation.Automation) })}
+                      </span>
+                      {status !== 'associated' && (
+                        <Tooltip.Trigger
+                          asChild
+                          side='bottom'
+                          content={t(
+                            status === 'pending' ? 'automation-not-associated.message' : 'automation-detached.message',
+                          )}
+                        >
+                          <Icon icon='ph--warning--regular' size={4} classNames='text-warning-text shrink-0 mr-2' />
+                        </Tooltip.Trigger>
+                      )}
+                    </Accordion.ItemHeader>
+                    <Accordion.ItemBody>
+                      <AutomationInlineForm automation={automation} db={db} />
+                    </Accordion.ItemBody>
+                  </Accordion.Item>
+                );
+              })}
+            </div>
+          )}
+        </Accordion.Root>
+      )}
+
+      <div className='border-t border-separator'>
+        <DropdownMenu.Root>
+          <DropdownMenu.Trigger asChild>
+            {/* Mirror the accordion item header layout (p-2 + icon mr-2) so the icon aligns with the rows above. */}
+            <button type='button' className='group flex items-center p-2 dx-focus-ring-inset w-full text-start'>
+              <Icon icon='ph--plus--regular' size={4} classNames='mr-2 shrink-0' />
+              <span className='flex-1 truncate'>
+                {t('add-object.label', { ns: Type.getTypename(Automation.Automation) })}
+              </span>
+            </button>
+          </DropdownMenu.Trigger>
+          <DropdownMenu.Portal>
+            <DropdownMenu.Content>
+              <DropdownMenu.Viewport>
+                {applicableTemplates.map((template) => (
+                  <DropdownMenu.Item key={template.id} onClick={() => void handleCreate(template.id)}>
+                    <Icon icon={template.icon ?? 'ph--lightning--regular'} size={4} />
+                    <span>{template.label}</span>
+                  </DropdownMenu.Item>
+                ))}
+              </DropdownMenu.Viewport>
+              <DropdownMenu.Arrow />
+            </DropdownMenu.Content>
+          </DropdownMenu.Portal>
+        </DropdownMenu.Root>
+      </div>
+    </div>
+  );
+};
+
+//
+// Hooks
+//
+
+/**
+ * Owns the companion's session-stable automation list. A reactive reverse-ref query supplies the live
+ * connected set, accumulated into an append-only ordering so rows never reorder or disappear while mounted;
+ * a row that loses its association (or a freshly-created one not yet connected) is surfaced via `statusFor`
+ * rather than dropped. Also holds the accordion open state and a create handler that appends the new
+ * automation and auto-expands it for immediate configuration.
+ */
+const useConnectedAutomations = (db: Database.Database, object: Obj.Unknown) => {
+  const { invokePromise } = useOperationInvoker();
+
+  // Live connected set (reactive reverse-ref query) + a by-id map for resolving rows that have left it.
+  const connected = useQuery(db, connectedAutomationsQuery(object));
+  const all = useQuery(db, Filter.type(Automation.Automation));
+  const connectedIds = useMemo(() => new Set(connected.map((automation) => automation.id)), [connected]);
+  const byId = useMemo(() => new Map(all.map((automation) => [automation.id, automation])), [all]);
+
+  // Session-stable bookkeeping (held for the component lifetime).
+  const seenOrder = useRef<string[]>([]);
+  const everConnected = useRef<Set<string>>(new Set());
+  const [createdIds, setCreatedIds] = useState<ReadonlySet<string>>(() => new Set());
+  const [open, setOpen] = useState<string[]>([]);
+
+  // Accumulate first-seen order and "was ever connected" — append-only, so rows never reorder or drop.
+  for (const id of connectedIds) {
+    everConnected.current.add(id);
+  }
+  for (const id of [...connectedIds, ...createdIds]) {
+    if (!seenOrder.current.includes(id)) {
+      seenOrder.current.push(id);
+    }
+  }
+
+  // Resolve to live objects in stable order, dropping ids whose object was hard-deleted.
+  const items = useMemo(
+    () =>
+      seenOrder.current.flatMap((id) => {
+        const automation = byId.get(id);
+        return automation ? [automation] : [];
+      }),
+    [byId, connectedIds, createdIds],
+  );
+
+  const statusFor = useCallback(
+    (id: string): Status =>
+      connectedIds.has(id) ? 'associated' : everConnected.current.has(id) ? 'detached' : 'pending',
+    [connectedIds],
+  );
+
+  const handleCreate = useCallback(
+    async (templateId: string) => {
+      const { data, error } = await invokePromise(AutomationOperation.CreateAutomation, {
+        db,
+        templateId,
+        subject: object,
+      });
+      if (error || !data) {
+        return;
+      }
+
+      setCreatedIds((prev) => new Set(prev).add(data.object.id));
+      setOpen((prev) => (prev.includes(data.object.id) ? prev : [...prev, data.object.id]));
+    },
+    [invokePromise, db, object],
+  );
+
+  return { items, statusFor, open, setOpen, handleCreate };
+};

package/src/containers/AutomationCompanion/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { AutomationCompanion as default } from './AutomationCompanion';
+export * from './AutomationCompanion';

package/src/containers/AutomationSettings/AutomationSettings.tsx

@@ -0,0 +1,34 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { AppSurface } from '@dxos/app-toolkit/ui';
+import { useTranslation } from '@dxos/react-ui';
+import { Settings } from '@dxos/react-ui-form';
+
+import { meta } from '#meta';
+
+import { TriggersSettings } from '../TriggerSettings';
+
+export type AutomationSettingsProps = AppSurface.SpaceArticleProps;
+
+/**
+ * Space-level automation settings. Individual automations are now first-class objects (configured in their
+ * article + per-object companion), so this page is focused on runtime management — where the space's
+ * automations execute.
+ */
+export const AutomationSettings = ({ space }: AutomationSettingsProps) => {
+  const { t } = useTranslation(meta.id);
+  return (
+    <Settings.Viewport>
+      <Settings.Section
+        title={t('automation-verbose.label', { ns: meta.id })}
+        description={t('automation.description', { ns: meta.id })}
+      >
+        <TriggersSettings space={space} />
+      </Settings.Section>
+    </Settings.Viewport>
+  );
+};

package/src/containers/AutomationSettings/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { AutomationSettings as default } from './AutomationSettings';

package/src/containers/TriggerSettings/TriggerSettings.tsx

@@ -0,0 +1,48 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { type ComputeEnvironment } from '@dxos/client-protocol';
+import { useObject } from '@dxos/echo-react';
+import { type Space } from '@dxos/react-client/echo';
+import { DropdownMenu, IconButton, useTranslation } from '@dxos/react-ui';
+import { Settings } from '@dxos/react-ui-form';
+
+import { meta } from '#meta';
+
+export const TriggersSettings = ({ space }: { space: Space }) => {
+  const { t } = useTranslation(meta.id);
+  const [properties, changeProperties] = useObject(space.properties);
+  const selected = properties.computeEnvironment ?? 'local';
+
+  const handleUpdate = (option: ComputeEnvironment) => {
+    changeProperties((draft) => {
+      draft.computeEnvironment = option;
+    });
+  };
+
+  return (
+    <div className='grid grid-cols-1 md:grid-cols-[1fr_min-content]'>
+      <Settings.Item title={t('runtime.label')} description={t('runtime.description')}>
+        <DropdownMenu.Root>
+          <DropdownMenu.Trigger asChild>
+            <IconButton iconEnd icon='ph--caret-down--regular' size={4} label={t(`runtime.${selected}.label`)} />
+          </DropdownMenu.Trigger>
+          <DropdownMenu.Portal>
+            <DropdownMenu.Content side='bottom'>
+              <DropdownMenu.Viewport>
+                <DropdownMenu.Item onClick={() => handleUpdate('disabled')}>
+                  {t(`runtime.disabled.label`)}
+                </DropdownMenu.Item>
+                <DropdownMenu.Item onClick={() => handleUpdate('local')}>{t(`runtime.local.label`)}</DropdownMenu.Item>
+                <DropdownMenu.Item onClick={() => handleUpdate('edge')}>{t(`runtime.edge.label`)}</DropdownMenu.Item>
+              </DropdownMenu.Viewport>
+            </DropdownMenu.Content>
+          </DropdownMenu.Portal>
+        </DropdownMenu.Root>
+      </Settings.Item>
+    </div>
+  );
+};

package/src/containers/TriggerSettings/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { TriggersSettings } from './TriggerSettings';
+export { TriggersSettings as default } from './TriggerSettings';

package/src/containers/index.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type ComponentType, lazy } from 'react';
+
+export const AutomationArticle: ComponentType<any> = lazy(() => import('./AutomationArticle'));
+export const AutomationSettings: ComponentType<any> = lazy(() => import('./AutomationSettings'));
+export const AutomationCompanion: ComponentType<any> = lazy(() => import('./AutomationCompanion'));
+export const TriggerSettings: ComponentType<any> = lazy(() => import('./TriggerSettings'));

package/src/hooks/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// TODO(wittjosiah): Factor out.
+export * from './useTriggerRuntimeControls';

package/src/hooks/useTriggerRuntimeControls.ts

@@ -0,0 +1,72 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Atom, useAtomValue } from '@effect-atom/atom-react';
+import type * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import { useEffect, useState } from 'react';
+
+import { useSpaceCallback } from '@dxos/app-framework/ui';
+import { Trigger } from '@dxos/compute';
+import { type Database, Filter, Query } from '@dxos/echo';
+import { TriggerDispatcher, type TriggerDispatcherState } from '@dxos/functions-runtime';
+import { useQuery } from '@dxos/react-client/echo';
+
+interface TriggerRuntimeControls {
+  triggers: Trigger.Trigger[];
+
+  state: TriggerDispatcherState | undefined;
+
+  start: () => void;
+  stop: () => void;
+}
+
+export const useTriggerRuntimeControls = (db: Database.Database | undefined): TriggerRuntimeControls => {
+  const triggers = useQuery(
+    db,
+    Query.select(Filter.type(Trigger.Trigger)).debugLabel('plugin-automation.useTriggerRuntimeControls'),
+  );
+
+  const [dispatcher, setDispatcher] = useState<Context.Tag.Service<TriggerDispatcher> | undefined>(undefined);
+
+  const init = useSpaceCallback(
+    db?.spaceId,
+    [TriggerDispatcher],
+    Effect.fnUntraced(function* () {
+      const dispatcher = yield* TriggerDispatcher;
+      setDispatcher(dispatcher);
+    }),
+  );
+
+  useEffect(() => {
+    void init();
+  }, []);
+
+  const state = useAtomValue(dispatcher?.state ?? Atom.make(undefined));
+
+  const start = useSpaceCallback(
+    db?.spaceId,
+    [TriggerDispatcher],
+    Effect.fnUntraced(function* () {
+      const dispatcher = yield* TriggerDispatcher;
+      yield* dispatcher.start();
+    }),
+  );
+
+  const stop = useSpaceCallback(
+    db?.spaceId,
+    [TriggerDispatcher],
+    Effect.fnUntraced(function* () {
+      const dispatcher = yield* TriggerDispatcher;
+      yield* dispatcher.stop();
+    }),
+  );
+
+  return {
+    triggers,
+    state,
+    start: () => void start(),
+    stop: () => void stop(),
+  };
+};

package/src/index.ts

@@ -2,7 +2,5 @@
 // Copyright 2023 DXOS.org
 //
 
-export * from './components';
 export * from './meta';
-
-export * from './AutomationPlugin';
+export * from './types';

package/src/meta.ts

@@ -2,15 +2,32 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type PluginMeta } from '@dxos/app-framework';
+import { Plugin } from '@dxos/app-framework';
+import { DXN } from '@dxos/keys';
+import { trim } from '@dxos/util';
 
-export const AUTOMATION_PLUGIN = 'dxos.org/plugin/automation';
-
-export const meta: PluginMeta = {
-  id: AUTOMATION_PLUGIN,
+export const meta = Plugin.makeMeta({
+  key: DXN.make('org.dxos.plugin.automation'),
   name: 'Automation',
-  description:
-    'The Automation tab allows you to trigger pre-defined workflows related to the element you are interacting with inside of Composer.',
-  icon: 'ph--robot--regular',
+  author: 'DXOS',
+  description: trim`
+    Event-driven workflow automation engine for DXOS Composer.
+    An Automation is a user-facing object pairing a trigger ("when" — a timer schedule or an
+    incoming feed) with an action ("then" — a persistent compute operation or routine), enabling
+    automated pipelines that react to changes in real time without manual intervention.
+
+    Automations are configured in their own article and surfaced on a per-object "Automations"
+    companion that lists the automations 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 blueprints 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 automations.
+  `,
+  icon: 'ph--atom--regular',
   source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-automation',
-};
+  spec: 'PLUGIN.mdl',
+  tags: ['system'],
+});

package/src/operations/create-automation.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+import { Database } from '@dxos/echo';
+import { invariant } from '@dxos/invariant';
+import { SpaceOperation } from '@dxos/plugin-space';
+
+import { getAutomationsPath } from '../paths';
+import { AutomationCapabilities, AutomationOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof AutomationOperation.CreateAutomation> =
+  AutomationOperation.CreateAutomation.pipe(
+    Operation.withHandler(
+      Effect.fnUntraced(function* ({ db, templateId, name, subject }) {
+        const templates = yield* Capability.getAll(AutomationCapabilities.Template);
+        const template = templates.find((entry) => entry.id === templateId);
+        invariant(template, `Unknown automation template: ${templateId}`);
+
+        const object = yield* template
+          .scaffold({ name, subject })
+          .pipe(Effect.provideService(Database.Service, Database.makeService(db)));
+
+        return yield* Operation.invoke(SpaceOperation.AddObject, {
+          object,
+          target: db,
+          hidden: true,
+          targetNodeId: getAutomationsPath(db.spaceId),
+        });
+      }),
+    ),
+  );
+
+export default handler;

package/src/operations/create-trigger-from-template.ts

@@ -0,0 +1,70 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { LayoutOperation, getSpacePath } from '@dxos/app-toolkit';
+import { Operation, Script, Trigger } from '@dxos/compute';
+import { type Feed, Filter, Obj, Ref } from '@dxos/echo';
+import { SpaceOperation } from '@dxos/plugin-space';
+
+import { meta } from '#meta';
+
+import { AutomationOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof AutomationOperation.CreateTriggerFromTemplate> =
+  AutomationOperation.CreateTriggerFromTemplate.pipe(
+    Operation.withHandler(
+      Effect.fnUntraced(function* ({ db, template, enabled = false, scriptName, input }) {
+        const trigger = Trigger.make({ enabled, input });
+
+        // TODO(wittjosiah): Factor out function lookup by script name?
+        if (scriptName) {
+          const scripts = yield* Effect.promise(() => db.query(Filter.type(Script.Script, { name: scriptName })).run());
+          const [script] = scripts;
+          if (script) {
+            const functions = yield* Effect.promise(() =>
+              db.query(Filter.type(Operation.PersistentOperation, { source: Ref.make(script) })).run(),
+            );
+            const [fn] = functions;
+            if (fn) {
+              Obj.update(trigger, (trigger) => {
+                trigger.function = Ref.make(fn);
+              });
+            }
+          }
+        }
+
+        switch (template.type) {
+          case 'timer': {
+            Obj.update(trigger, (trigger) => {
+              trigger.spec = Trigger.specTimer(template.cron);
+            });
+            break;
+          }
+          case 'feed': {
+            Obj.update(trigger, (trigger) => {
+              trigger.spec = Trigger.specFeed(template.feed as Feed.Feed);
+            });
+            break;
+          }
+          default: {
+            break;
+          }
+        }
+
+        yield* Operation.invoke(SpaceOperation.AddObject, {
+          object: trigger,
+          target: db,
+          hidden: true,
+        });
+        yield* Operation.invoke(LayoutOperation.Open, {
+          subject: [`${getSpacePath(db.spaceId)}/settings/${meta.id}.automations`],
+          workspace: getSpacePath(db.spaceId),
+        });
+      }),
+    ),
+  );
+
+export default handler;

package/src/operations/index.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/compute';
+
+export const AutomationOperationHandlerSet = OperationHandlerSet.lazy(
+  () => import('./create-trigger-from-template'),
+  () => import('./create-automation'),
+);

package/src/paths.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { createTypeSectionPaths } from '@dxos/app-toolkit';
+
+import { Automation } from '#types';
+
+const { getSectionPath: getAutomationsPath, getObjectPath: getAutomationPath } = createTypeSectionPaths(
+  Automation.Automation,
+);
+
+export { getAutomationsPath, getAutomationPath };

package/src/plugin.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from './meta';
+
+export const AutomationPlugin = Plugin.lazy(meta, () => import('#plugin'));
+
+export { AutomationOperationHandlerSet } from './operations';

package/src/templates/index.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Automation, type AutomationCapabilities } from '#types';
+
+/**
+ * Blank template: mints an empty automation with no runnable and no triggers; the action and trigger are
+ * configured in the automation article. This is the no-op template (the create dialog's default), so the
+ * create flow has a single resolve→scaffold path with no special-casing.
+ */
+export const blank: AutomationCapabilities.Template = {
+  id: 'org.dxos.automation.blank',
+  label: 'Blank',
+  icon: 'ph--lightning--regular',
+  scaffold: ({ name }) => Effect.succeed(Automation.make({ name, triggers: [] })),
+};
+
+/** Templates contributed by plugin-automation itself. */
+export const defaultTemplates: AutomationCapabilities.Template[] = [blank];