@dxos/plugin-routine 0.0.0

package/src/containers/RoutineArticle/RoutineArticle.tsx

@@ -0,0 +1,109 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Atom, RegistryContext } from '@effect-atom/atom-react';
+import React, { useCallback, useContext, useMemo } from 'react';
+
+import { useOperationInvoker } from '@dxos/app-framework/ui';
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { Obj, Ref } from '@dxos/echo';
+import { useObject } from '@dxos/react-client/echo';
+import { Panel } from '@dxos/react-ui';
+import { Menu, MenuBuilder, useMenuBuilder } from '@dxos/react-ui-menu';
+
+import { RoutineForm } from '#components';
+import { meta } from '#meta';
+import { Routine, RoutineOperation } from '#types';
+
+export type RoutineArticleProps = AppSurface.ObjectArticleProps<Routine.Routine>;
+
+/**
+ * Article surface for a {@link Routine}. The form edits the live routine in place; each trigger's on/off state
+ * is toggled inline in the trigger editor. The toolbar exposes Run.
+ *
+ * TODO(wittjosiah): Disable editing while the routine is running (you shouldn't mutate running code). This was
+ * previously wired as "read-only when enabled" via a routine-level toggle, but that is not how we want to
+ * achieve it — reintroduce a run-state-based lock instead.
+ */
+export const RoutineArticle = ({ role, attendableId, subject }: RoutineArticleProps) => {
+  const { invokePromise } = useOperationInvoker();
+  const registry = useContext(RegistryContext);
+  // Subscribe so the run affordance tracks the routine's action (`spec`).
+  const [routine] = useObject(subject);
+  const db = Obj.getDatabase(subject);
+
+  const runningAtom = useMemo(() => Atom.make(false), []);
+
+  // Require both a spec and at least one trigger: manual runs are attributed to the first trigger
+  // so they appear in history, and without a trigger the run would be invisible there.
+  const canRun = useMemo(() => Boolean(routine.spec) && routine.triggers.length > 0, [routine.spec, routine.triggers]);
+
+  const handleRun = useCallback(() => {
+    if (!invokePromise || !db) {
+      return;
+    }
+    // Thread the routine's first trigger as trace attribution so the run appears in history.
+    // Manual runs bypass the trigger dispatcher (which normally stamps meta.trigger), so we
+    // do it here — history filters on trigger entity id, and without this the run is invisible.
+    const triggerRef = routine.triggers[0];
+    registry.set(runningAtom, true);
+    void invokePromise(
+      RoutineOperation.RunRoutine,
+      { routine: Ref.make(subject) },
+      {
+        spaceId: db.spaceId,
+        notify: { error: ['run-error.message', { ns: meta.profile.key }] },
+        ...(triggerRef ? { tracing: { trigger: triggerRef } } : {}),
+      },
+    ).finally(() => registry.set(runningAtom, false));
+  }, [invokePromise, db, subject, routine, registry, runningAtom]);
+
+  const menuActions = useArticleMenuActions({ canRun, runningAtom, handleRun });
+
+  if (!db) {
+    return null;
+  }
+
+  return (
+    <Menu.Root {...menuActions} attendableId={attendableId}>
+      <Panel.Root role={role}>
+        <Panel.Toolbar>
+          <Menu.Toolbar className='dx-document' />
+        </Panel.Toolbar>
+        <Panel.Content>
+          <RoutineForm db={db} routine={subject} />
+        </Panel.Content>
+      </Panel.Root>
+    </Menu.Root>
+  );
+};
+
+//
+// Hooks
+//
+
+type ArticleMenuActionsOptions = {
+  canRun: boolean;
+  runningAtom: Atom.Writable<boolean>;
+  handleRun: () => void;
+};
+
+const useArticleMenuActions = ({ canRun, runningAtom, handleRun }: ArticleMenuActionsOptions) =>
+  useMenuBuilder(
+    (get) =>
+      MenuBuilder.make()
+        .action(
+          'run',
+          {
+            label: ['run.label', { ns: meta.profile.key }],
+            icon: 'ph--play--regular',
+            disabled: get(runningAtom) || !canRun,
+            disposition: 'toolbar',
+            testId: 'routine.toolbar.run',
+          },
+          () => handleRun(),
+        )
+        .build(),
+    [canRun, handleRun, runningAtom],
+  );

package/src/containers/RoutineArticle/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { type RoutineArticleProps, RoutineArticle as default } from './RoutineArticle';

package/src/containers/RoutineCompanion/RoutineCompanion.stories.tsx

@@ -0,0 +1,82 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import React from 'react';
+
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { Instructions, Skill } from '@dxos/compute';
+import { Filter, Ref } from '@dxos/echo';
+import { ClientPlugin } from '@dxos/plugin-client/testing';
+import { RoutinePlugin } from '@dxos/plugin-routine/testing';
+import { corePlugins } from '@dxos/plugin-testing';
+import { type Space, useQuery, useSpaces } from '@dxos/react-client/echo';
+import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';
+import { Text } from '@dxos/schema';
+
+import { translations } from '#translations';
+import { Routine } from '#types';
+
+import { RoutineCompanion } from './RoutineCompanion';
+
+const types = [Routine.Routine, Instructions.Instructions, Skill.Skill, Text.Text];
+
+/** Seed a companion-subject object plus one automation connected via instructions.objects. */
+const seed = (space: Space) => {
+  const subject = space.db.add(Text.make({ content: 'Meeting notes' }));
+
+  space.db.add(
+    Routine.make({
+      name: 'Summarize Notes',
+      instructions: Instructions.make({ name: 'Summarize notes', objects: [Ref.make(subject)] }),
+    }),
+  );
+};
+
+const withCompanion = () =>
+  withPluginManager({
+    plugins: [
+      ...corePlugins(),
+      ClientPlugin({
+        types,
+        onClientInitialized: ({ client }) =>
+          Effect.gen(function* () {
+            yield* Effect.promise(() => client.halo.createIdentity());
+            const space = yield* Effect.promise(() => client.spaces.create());
+            yield* Effect.promise(() => space.waitUntilReady());
+            seed(space);
+          }),
+      }),
+      RoutinePlugin(),
+    ],
+  });
+
+const DefaultStory = () => {
+  const spaces = useSpaces();
+  const space = spaces[spaces.length - 1];
+  const [subject] = useQuery(space?.db, Filter.type(Text.Text));
+  if (!subject || !space?.db) {
+    return <Loading />;
+  }
+  return <RoutineCompanion attendableId={subject.id} subject={subject} />;
+};
+
+const meta = {
+  title: 'plugins/plugin-routine/containers/RoutineCompanion',
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  decorators: [withCompanion()],
+};

package/src/containers/RoutineCompanion/RoutineCompanion.tsx

@@ -0,0 +1,342 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Atom } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+import React, { useCallback, useMemo, useRef, useState } from 'react';
+
+import { useCapabilities, useOperationInvoker } from '@dxos/app-framework/ui';
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { Database, Filter, Obj, Type } from '@dxos/echo';
+import { EffectEx } from '@dxos/effect';
+import { SpaceOperation } from '@dxos/plugin-space';
+import { useQuery } from '@dxos/react-client/echo';
+import { Panel, ScrollArea, useTranslation } from '@dxos/react-ui';
+import { type ActionGraphProps, Menu, MenuBuilder, useMenuBuilder } from '@dxos/react-ui-menu';
+
+import { MasterDetail, type MasterDetailAdornment, type MasterDetailIcon, RoutineForm } from '#components';
+import { meta } from '#meta';
+import { Routine, RoutineCapabilities } from '#types';
+
+import { connectedRoutinesQuery } from '../../util';
+
+/** Association state of a row relative to the companion's object. */
+type Status = 'associated' | 'detached';
+
+export type RoutineCompanionProps = AppSurface.ObjectArticleProps<Obj.Unknown>;
+
+/**
+ * Per-object companion: a master-detail list of automations connected to the object, via
+ * {@link connectedRoutinesQuery} (covers both trigger-input and instructions-context paths).
+ *
+ * The list is session-stable: a routine seen connected stays listed even after it loses its association
+ * (flagged with a 'detached' adornment) so it doesn't vanish mid-edit. The toolbar create menu offers a
+ * template picker (contributed via {@link RoutineCapabilities.Template}, filtered by `appliesTo`); each
+ * template's `scaffold` returns a fully-wired in-memory routine graph, shown editable in {@link RoutineForm}
+ * and committed on Save with a single `Database.add` (which cascades the owned children). Existing routines
+ * are edited in place.
+ */
+export const RoutineCompanion = ({ subject: object, attendableId }: RoutineCompanionProps) => {
+  // A non-persisted subject has no database; `db` may be undefined. Every hook below tolerates that, and the
+  // render is guarded after the last hook (see below) so hook order is identical across renders either way.
+  const db = Obj.getDatabase(object);
+
+  const { t } = useTranslation(meta.profile.key);
+  const { invokePromise } = useOperationInvoker();
+  const { items, statusFor } = useConnectedRoutines(db, object);
+
+  const [selectedId, setSelectedId] = useState<string | undefined>();
+  const [draft, setDraft] = useState<Routine.Routine | undefined>();
+  // After saving a draft, hold the persisted routine directly so the detail panel renders immediately
+  // before the reactive queries catch up to include the newly-connected routine.
+  const [savedRoutine, setSavedRoutine] = useState<Routine.Routine | undefined>();
+  const selected = useMemo(
+    () => items.find((routine) => routine.id === selectedId) ?? savedRoutine,
+    [items, selectedId, savedRoutine],
+  );
+
+  const handleSelect = useCallback(
+    (id: string | undefined) => {
+      // Ignore selection changes while a draft is active — the edit (or create) must be saved or cancelled first.
+      if (draft) {
+        return;
+      }
+      setSavedRoutine(undefined);
+      setSelectedId(id);
+    },
+    [draft],
+  );
+
+  const handleCreateFromTemplate = useCallback(
+    async (template: RoutineCapabilities.Template) => {
+      if (!db) {
+        return;
+      }
+
+      // The scaffold returns a fully-wired in-memory routine draft graph (its owned trigger/instructions
+      // bound and parented); nothing is persisted until Save.
+      const scaffolded = await EffectEx.runPromise(
+        template.scaffold({ subject: object }).pipe(Effect.provideService(Database.Service, Database.makeService(db))),
+      );
+
+      setSavedRoutine(undefined);
+      setSelectedId(undefined);
+      setDraft(scaffolded);
+    },
+    [db, object],
+  );
+
+  // Templates filtered to those applicable to this companion's subject.
+  const allTemplates = useCapabilities(RoutineCapabilities.Template);
+  const templates = useMemo(
+    () => allTemplates.filter((template) => template.appliesTo?.(object) ?? true),
+    [allTemplates, object],
+  );
+
+  // Toolbar create menu: a `+` dropdown of applicable templates, pushed to the trailing edge by a growing gap
+  // separator (disabled while a draft is in progress so it can't be silently replaced).
+  const menuActions = useCompanionMenuActions({ t, templates, draft, handleCreateFromTemplate });
+
+  const handleCancel = useCallback(() => {
+    // Draft was never persisted, nothing to clean up.
+    setDraft(undefined);
+  }, []);
+
+  const handleSave = useCallback(async () => {
+    if (!draft || !db) {
+      return;
+    }
+
+    // The draft is a fully-wired graph (see `Routine.make`); a single add cascades the owned trigger and
+    // instructions, and the subject carried in the instructions' `objects` is the structural connection the
+    // query finds.
+    const persistedRoutine = db.add(draft);
+    await db.flush();
+    setSelectedId(persistedRoutine.id);
+    // Provide the persisted routine directly so the detail panel renders before the reactive queries
+    // catch up to include the newly-connected routine.
+    setSavedRoutine(persistedRoutine);
+    setDraft(undefined);
+  }, [draft, db]);
+
+  const handleDelete = useCallback(
+    (routine: Routine.Routine) => {
+      if (!db) {
+        return;
+      }
+
+      setSavedRoutine((current) => (current?.id === routine.id ? undefined : current));
+      setSelectedId((current) => (current === routine.id ? undefined : current));
+      // Route through the space operation so the deletion is undoable (toast + RestoreObjects), rather than
+      // mutating the database directly.
+      void invokePromise?.(SpaceOperation.RemoveObjects, { objects: [routine] }, { spaceId: db.spaceId });
+    },
+    [invokePromise, db],
+  );
+
+  // Per-row overflow menu: delete. (A routine's on/off state is toggled per-trigger inline in the form,
+  // not from the list.)
+  const getMenu = useGetMenu({ t, handleDelete });
+
+  // Row icon, reactive per row: an enabled routine takes its type's hue (amber); disabled uses the default
+  // icon colour. Subscribes (via `get`) only to this routine's triggers' `enabled` flags.
+  const getIcon = useCallback((get: Atom.Context, routine: Routine.Routine): MasterDetailIcon => {
+    const { icon, hue } = Obj.getIcon(routine) ?? { icon: 'ph--lightning--regular', hue: undefined };
+    const { enabled } = get(routineEnabled(routine));
+    return { icon, hue: enabled ? hue : undefined };
+  }, []);
+
+  // Row label, reactive per row via the object's label atom, so a rename updates the row live.
+  const getLabel = useCallback(
+    (get: Atom.Context, routine: Routine.Routine): string =>
+      get(Obj.labelAtom(routine)) || t('object-name.placeholder', { ns: Type.getTypename(Routine.Routine) }) || '',
+    [t],
+  );
+
+  // Trailing adornment: a warning badge on a row whose routine has left the connected set (it stays in the
+  // session-stable list — see {@link useConnectedRoutines} — rather than disappearing while still selected/edited).
+  const getAdornment = useCallback(
+    (_get: Atom.Context, routine: Routine.Routine): MasterDetailAdornment | undefined =>
+      statusFor(routine.id) === 'detached'
+        ? { icon: 'ph--warning--regular', label: t('routine-detached.message') }
+        : undefined,
+    [statusFor, t],
+  );
+
+  // Render guard placed after every hook so hook order stays stable: a non-persisted subject (no database)
+  // has nothing to list.
+  if (!db) {
+    return null;
+  }
+
+  // One form for both flows. A selected (persisted) routine is edited in place. The create-from-template draft
+  // is the only Save/Cancel flow: an in-memory routine shown editable, discarded on Cancel and persisted by a
+  // single `Database.add` on Save. The `key` (the routine id) remounts the uncontrolled form when the shown
+  // routine changes; the draft carries a fresh id, so no edits leak between rows.
+  const shown = draft ?? selected;
+  const detail = shown ? (
+    <RoutineForm
+      key={shown.id}
+      db={db}
+      routine={shown}
+      onSave={draft ? () => void handleSave() : undefined}
+      onCancel={draft ? handleCancel : undefined}
+    />
+  ) : null;
+
+  return (
+    <Menu.Root {...menuActions} attendableId={attendableId}>
+      <Panel.Root>
+        <Panel.Toolbar>
+          <Menu.Toolbar className='dx-document' />
+        </Panel.Toolbar>
+        <Panel.Content asChild className='pt-trim-md'>
+          <ScrollArea.Root>
+            <ScrollArea.Viewport>
+              <MasterDetail<Routine.Routine>
+                classNames='dx-document'
+                items={items}
+                selectedId={selectedId}
+                detail={detail}
+                onSelect={handleSelect}
+                getMenu={getMenu}
+                getIcon={getIcon}
+                getLabel={getLabel}
+                getAdornment={getAdornment}
+                emptyLabel={t('no-routines.message')}
+              />
+            </ScrollArea.Viewport>
+          </ScrollArea.Root>
+        </Panel.Content>
+      </Panel.Root>
+    </Menu.Root>
+  );
+};
+
+//
+// Hooks
+//
+
+/**
+ * The companion's automation list, session-stable and frozen against disconnection: routines connected to the
+ * object via {@link connectedRoutinesQuery} (trigger-input and instructions-context paths unified) are
+ * accumulated append-only so rows never reorder, and a routine that leaves the connected set stays in the list
+ * (flagged `detached` via {@link statusFor}) rather than vanishing mid-edit — only a hard-deleted routine drops
+ * out. Detached rows are resolved from the space's full routine set since the connected query no longer returns
+ * them. A freshly-saved routine appears once the query reflects it.
+ */
+const useConnectedRoutines = (
+  db: Database.Database | undefined,
+  object: Obj.Unknown,
+): { items: Routine.Routine[]; statusFor: (id: string) => Status } => {
+  const connected = useQuery(db, connectedRoutinesQuery(object));
+  const connectedIds = useMemo(() => new Set(connected.map((routine) => routine.id)), [connected]);
+
+  // All routines in the space — used to resolve rows that have left the connected set (still exist, just detached).
+  const all = useQuery(db, Filter.type(Routine.Routine));
+  const byId = useMemo(() => new Map(all.map((routine) => [routine.id, routine])), [all]);
+
+  // Session-stable, append-only: a routine seen connected this session is remembered so its row never reorders
+  // or disappears on disconnect. Scoped to the current subject — reset if this instance is reused for another
+  // object so the previous subject's rows don't leak in.
+  const seenOrder = useRef<string[]>([]);
+  const seenForObject = useRef(object.id);
+  if (seenForObject.current !== object.id) {
+    seenForObject.current = object.id;
+    seenOrder.current = [];
+  }
+  for (const id of connectedIds) {
+    if (!seenOrder.current.includes(id)) {
+      seenOrder.current.push(id);
+    }
+  }
+
+  // Resolve to live objects in stable order, dropping only ids whose routine was hard-deleted.
+  const items = useMemo(
+    () => seenOrder.current.flatMap((id) => (byId.has(id) ? [byId.get(id)!] : [])),
+    [byId, connectedIds],
+  );
+
+  const statusFor = useCallback(
+    (id: string): Status => (connectedIds.has(id) ? 'associated' : 'detached'),
+    [connectedIds],
+  );
+
+  return { items, statusFor };
+};
+
+/**
+ * Reactive family for a routine's on/off state — subscribes (via `get`) to its triggers' `enabled` flags so the
+ * row icon re-derives when a flag flips. Keyed by the routine instance.
+ */
+const routineEnabled = Atom.family(
+  (routine: Routine.Routine): Atom.Atom<{ hasTriggers: boolean; enabled: boolean }> =>
+    Atom.make((get) => {
+      const triggers = get(Obj.atomProperty(routine, 'triggers'));
+      const hasTriggers = triggers.length > 0;
+      return {
+        hasTriggers,
+        enabled: hasTriggers && triggers.every((ref) => get(Obj.atomProperty(ref, 'enabled')) === true),
+      };
+    }),
+);
+
+type GetMenuOptions = {
+  t: ReturnType<typeof useTranslation>['t'];
+  handleDelete: (routine: Routine.Routine) => void;
+};
+
+const useGetMenu = ({ t, handleDelete }: GetMenuOptions) =>
+  useCallback(
+    (_get: Atom.Context, routine: Routine.Routine): ActionGraphProps =>
+      MenuBuilder.make()
+        .action(
+          'delete',
+          {
+            label: t('delete.label'),
+            icon: 'ph--trash--regular',
+            testId: 'routine.companion.delete',
+          },
+          () => handleDelete(routine),
+        )
+        .build(),
+    [t, handleDelete],
+  );
+
+type CompanionMenuActionsOptions = {
+  t: ReturnType<typeof useTranslation>['t'];
+  templates: RoutineCapabilities.Template[];
+  draft: Routine.Routine | undefined;
+  handleCreateFromTemplate: (template: RoutineCapabilities.Template) => Promise<void>;
+};
+
+const useCompanionMenuActions = ({ t, templates, draft, handleCreateFromTemplate }: CompanionMenuActionsOptions) =>
+  useMenuBuilder(
+    () =>
+      MenuBuilder.make()
+        .separator('gap')
+        .group(
+          'create',
+          {
+            variant: 'dropdownMenu',
+            label: t('add-routine.label'),
+            icon: 'ph--plus--regular',
+            iconOnly: true,
+            caretDown: false,
+            disabled: draft != null || templates.length === 0,
+            testId: 'routine.companion.create',
+          },
+          (group) => {
+            for (const template of templates) {
+              group.action(
+                template.id,
+                { label: template.label, icon: template.icon ?? 'ph--lightning--regular' },
+                () => void handleCreateFromTemplate(template),
+              );
+            }
+          },
+        )
+        .build(),
+    [t, templates, draft, handleCreateFromTemplate],
+  );

package/src/containers/RoutineCompanion/index.ts

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

package/src/containers/RoutineSettings/RoutineSettings.tsx

@@ -0,0 +1,65 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { AppSurface } from '@dxos/app-toolkit/ui';
+import { type ComputeEnvironment } from '@dxos/client-protocol';
+import { useObject } from '@dxos/echo-react';
+import { DropdownMenu, IconButton, useTranslation } from '@dxos/react-ui';
+import { Form } from '@dxos/react-ui-form';
+
+import { meta } from '#meta';
+
+export type RoutineSettingsProps = AppSurface.SpaceArticleProps;
+
+/**
+ * Space-level routine settings. Individual routines are now first-class objects (configured in their
+ * article + per-object companion), so this page is focused on runtime management — where the space's
+ * routines execute.
+ */
+export const RoutineSettings = ({ space }: RoutineSettingsProps) => {
+  const { t } = useTranslation(meta.profile.key);
+  const [properties, changeProperties] = useObject(space.properties);
+  const selected = properties.computeEnvironment ?? 'local';
+
+  const handleUpdate = (option: ComputeEnvironment) => {
+    changeProperties((draft) => {
+      draft.computeEnvironment = option;
+    });
+  };
+
+  return (
+    <Form.Root variant='settings'>
+      <Form.Viewport scroll>
+        <Form.Content>
+          <Form.Section title={t('routine-verbose.label')} description={t('routine.description')}>
+            <Form.Row label={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>
+            </Form.Row>
+          </Form.Section>
+        </Form.Content>
+      </Form.Viewport>
+    </Form.Root>
+  );
+};

package/src/containers/RoutineSettings/index.ts

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