@dxos/plugin-routine 0.0.0

package/src/hooks/useTriggerRuntimeControls.ts

@@ -0,0 +1,70 @@
+//
+// 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-routine.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

@@ -0,0 +1,7 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './meta';
+export * from './paths';
+export * from './types';

package/src/meta.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import config from '../dx.config';
+
+export const meta = Plugin.getMetaFromConfig(config);

package/src/operations/create-routine.ts

@@ -0,0 +1,39 @@
+//
+// 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 { getRoutinesPath } from '../paths';
+import { RoutineCapabilities, RoutineOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof RoutineOperation.CreateRoutine> = RoutineOperation.CreateRoutine.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ db, templateId, name, subject }) {
+      const templates = yield* Capability.getAll(RoutineCapabilities.Template);
+      const template = templates.find((entry) => entry.id === templateId);
+      invariant(template, `Unknown routine template: ${templateId}`);
+
+      // The scaffold returns a fully-wired in-memory routine graph (runnable, owned instructions, and trigger
+      // all parented and bound by `Routine.make`); AddObject's `Database.add` cascades the whole graph.
+      const draft = yield* template
+        .scaffold({ name, subject })
+        .pipe(Effect.provideService(Database.Service, Database.makeService(db)));
+
+      const targetNodeId = getRoutinesPath(db.spaceId);
+      return yield* Operation.invoke(SpaceOperation.AddObject, {
+        object: draft,
+        target: db,
+        targetNodeId,
+      });
+    }),
+  ),
+);
+
+export default handler;

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

@@ -0,0 +1,68 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { LayoutOperation, Paths } 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 { getRoutinesSettingsPath } from '../paths';
+import { RoutineOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof RoutineOperation.CreateTriggerFromTemplate> =
+  RoutineOperation.CreateTriggerFromTemplate.pipe(
+    Operation.withHandler(
+      Effect.fnUntraced(function* ({ db, template, enabled = false, scriptName, input }) {
+        const trigger = Trigger.make({ enabled, input });
+
+        // TODO(wittjosiah): Factor out operation 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 operations = yield* Effect.promise(() =>
+              db.query(Filter.type(Operation.PersistentOperation, { source: Ref.make(script) })).run(),
+            );
+            const [operation] = operations;
+            if (operation) {
+              Obj.update(trigger, (trigger) => {
+                trigger.runnable = Ref.make(operation);
+              });
+            }
+          }
+        }
+
+        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,
+        });
+        yield* Operation.invoke(LayoutOperation.Open, {
+          subject: [getRoutinesSettingsPath(db.spaceId)],
+          workspace: Paths.getSpacePath(db.spaceId),
+        });
+      }),
+    ),
+  );
+
+export default handler;

package/src/operations/index.ts

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

package/src/operations/run-routine.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { RunInstructions } from '@dxos/assistant-toolkit';
+import { Operation } from '@dxos/compute';
+import { Database, Obj } from '@dxos/echo';
+import { invariant } from '@dxos/invariant';
+
+import { RoutineOperation } from '../types';
+
+// A routine's action is its `runnable`: either an Operation (invoked directly) or the routine's owned
+// Instructions object (run as a background process — the same path triggers use — without creating a new
+// Chat session object).
+const handler: Operation.WithHandler<typeof RoutineOperation.RunRoutine> = RoutineOperation.RunRoutine.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ routine }) {
+      const routineObj = yield* Database.load(routine);
+      const db = Obj.getDatabase(routineObj);
+      invariant(db, 'Routine is not attached to a database.');
+
+      // The action kind is explicit in `spec`; dispatch by kind rather than dereferencing to classify.
+      const spec = routineObj.spec;
+      if (spec?.kind === 'instructions') {
+        // The instructions carry their own context objects and skills; RunInstructions binds them when it
+        // executes. No Chat session object is created — the run appears in the process monitor only.
+        yield* Operation.schedule(
+          RunInstructions,
+          { instructions: spec.instructions, input: {} },
+          { spaceId: db.spaceId },
+        );
+        return;
+      }
+
+      invariant(spec?.kind === 'runnable', 'Routine has no action to run.');
+      const operation = yield* Database.load(spec.runnable);
+      invariant(Obj.instanceOf(Operation.PersistentOperation, operation), 'Routine has no action to run.');
+      yield* Operation.invoke(Operation.deserialize(operation));
+    }),
+  ),
+);
+
+export default handler;

package/src/paths.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Paths } from '@dxos/app-toolkit';
+
+import { meta } from '#meta';
+import { Routine } from '#types';
+
+const { getSectionPath: getRoutinesPath } = Paths.createTypeSectionPaths(Routine.Routine, {
+  groupId: Paths.GroupSegments.ai,
+});
+
+/** Path to the routines settings section for a given space. */
+export const getRoutinesSettingsPath = (spaceId: string): string =>
+  Paths.getSpacePath(spaceId, 'settings', `${meta.profile.key}.routines`);
+
+export { getRoutinesPath };

package/src/plugin.ts

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

package/src/templates/index.ts

@@ -0,0 +1,48 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+import { AppAnnotation } from '@dxos/app-toolkit';
+import { Instructions, Skill, Trigger } from '@dxos/compute';
+import { Obj, Ref, Type } from '@dxos/echo';
+
+import { Routine, type RoutineCapabilities } from '#types';
+
+/**
+ * Blank template: an instructions-action routine draft with an empty trigger; the action kind, schedule, and
+ * body are configured in the form. In an object companion the instructions are seeded with the subject (in
+ * `objects`) and its type's skills so the draft starts associated with the subject; the global create dialog
+ * (no subject) starts with bare instructions.
+ */
+export const blank: RoutineCapabilities.Template = {
+  id: 'org.dxos.routine.blank',
+  label: 'Blank',
+  icon: 'ph--lightning--regular',
+  scaffold: ({ name, subject }) =>
+    Effect.succeed(
+      Routine.make({
+        name,
+        instructions: Instructions.make({
+          skills: subject ? skillRefsForObject(subject) : [],
+          objects: subject ? [Ref.make(subject)] : undefined,
+        }),
+        trigger: Trigger.make({}),
+      }),
+    ),
+};
+
+/** Templates contributed by plugin-routine itself. */
+export const defaultTemplates: RoutineCapabilities.Template[] = [blank];
+
+/** Registry skill refs declared by the object type's {@link AppAnnotation.SkillsAnnotation}. */
+const skillRefsForObject = (object: Obj.Unknown): Ref.Ref<Skill.Skill>[] => {
+  const type = Obj.getType(object);
+  if (!type) {
+    return [];
+  }
+  const keys = Option.getOrElse(() => [] as string[])(AppAnnotation.SkillsAnnotation.get(Type.getSchema(type)));
+  return keys.map((key) => Ref.fromURI(Skill.registryURI(key)));
+};

package/src/testing/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './test-functions';

package/src/testing/test-functions.ts

@@ -0,0 +1,76 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { TestSchema } from '@dxos/client/testing';
+import { DXN, JsonSchema, Ref } from '@dxos/echo';
+
+/**
+ * Operations seeded into the local space in stories.
+ */
+export const functions = [
+  {
+    key: DXN.make('com.example.function.chess'),
+    name: 'com.example.function.chess',
+    version: '0.1.0',
+    inputSchema: JsonSchema.toJsonSchema(
+      Schema.Struct({
+        level: Schema.Number.annotations({
+          title: 'Level',
+        }),
+      }),
+    ),
+  },
+  {
+    key: DXN.make('com.example.function.forex'),
+    name: 'com.example.function.forex',
+    version: '0.1.0',
+    binding: 'FOREX',
+    inputSchema: JsonSchema.toJsonSchema(
+      Schema.Struct({
+        from: Schema.String.annotations({ title: 'Currency from' }),
+        to: Schema.String.annotations({ title: 'Currency to' }),
+      }),
+    ),
+  },
+  {
+    key: DXN.make('com.example.function.pingContact'),
+    name: 'com.example.function.ping-contact',
+    version: '0.0.1',
+    inputSchema: JsonSchema.toJsonSchema(
+      Schema.Struct({
+        contact: Ref.Ref(TestSchema.ContactType).annotations({ title: 'Contact' }),
+      }),
+    ),
+  },
+];
+
+/**
+ * Operations seeded into the registry (not the local space) in stories.
+ * Simulates built-in or plugin-provided operations available globally.
+ */
+export const registryFunctions = [
+  {
+    key: 'com.example.function.translate',
+    name: 'com.example.function.translate',
+    version: '0.1.0',
+    inputSchema: JsonSchema.toJsonSchema(
+      Schema.Struct({
+        text: Schema.String.annotations({ title: 'Text' }),
+        targetLanguage: Schema.String.annotations({ title: 'Target language' }),
+      }),
+    ),
+  },
+  {
+    key: 'com.example.function.summarize',
+    name: 'com.example.function.summarize',
+    version: '0.1.0',
+    inputSchema: JsonSchema.toJsonSchema(
+      Schema.Struct({
+        content: Schema.String.annotations({ title: 'Content' }),
+      }),
+    ),
+  },
+];

package/src/testing.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// Eager re-export of `RoutinePlugin`. See `@dxos/plugin-testing/src/core.ts`
+// for the rationale.
+export * from './RoutinePlugin';

package/src/translations.ts

@@ -0,0 +1,125 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Type } from '@dxos/echo';
+import { type Resource } from '@dxos/react-ui';
+import { translations as componentsTranslations } from '@dxos/react-ui-components/translations';
+import { translations as formTranslations } from '@dxos/react-ui-form/translations';
+
+import { meta } from '#meta';
+import { Routine } from '#types';
+
+export const translations: Resource[] = [
+  ...componentsTranslations,
+  ...formTranslations,
+  {
+    'en-US': {
+      [Type.getTypename(Routine.Routine)]: {
+        'typename.label': 'Routine',
+        'typename.label_zero': 'Routines',
+        'typename.label_one': 'Routine',
+        'typename.label_other': 'Routines',
+        'object-name.placeholder': 'New routine',
+        'add-object.label': 'Add routine',
+        'rename-object.label': 'Rename routine',
+        'delete-object.label': 'Delete routine',
+      },
+      [meta.profile.key]: {
+        'plugin.name': 'Routine',
+        'automation-panel.label': 'Routines',
+        'create-panel.template.placeholder': 'Search templates...',
+
+        'schedule.kind.once.label': 'Once',
+        'schedule.kind.hourly.label': 'Hourly',
+        'schedule.kind.daily.label': 'Daily',
+        'schedule.kind.weekly.label': 'Weekly',
+        'schedule.kind.monthly.label': 'Monthly',
+        'schedule.kind.custom.label': 'Custom',
+        'schedule.at.label': 'At',
+        'schedule.on.label': 'On',
+        'schedule.minute.label': 'At minute',
+        'schedule.day.label': 'Day of month',
+        'schedule.cron.label': 'Cron',
+        'schedule.close.label': 'Close',
+        'schedule.note.message': 'Runs are staggered by a few minutes to spread server load.',
+
+        'command.placeholder': 'Enter slash command...',
+        'template.placeholder': 'Enter template...',
+        'run-prompt.label': 'Run prompt',
+        'routine-running.label': 'Running…',
+        'run.label': 'Run',
+        'run-error.message': 'Failed to run routine.',
+
+        'automation-name.label': 'Name',
+        'general.title': 'General',
+        'general.description': 'Name and description.',
+
+        'actions.title': 'Actions',
+        'actions.description': 'What this routine runs.',
+        'action.placeholder': 'Select an operation or instructions',
+        'action-input.label': 'Input',
+        'action-kind.operation.label': 'Operation',
+        'action-kind.instructions.label': 'Instructions',
+
+        'triggers.title': 'Triggers',
+        'triggers.description': 'When this routine runs.',
+        'trigger-kind.placeholder': 'Select trigger type',
+        'trigger-kind.timer.label': 'Schedule',
+        'trigger-kind.timer.description': 'Run on a recurring schedule or once at a future time.',
+        'trigger-kind.subscription.label': 'Query',
+        'trigger-kind.subscription.description': 'Run when objects matching a query change.',
+        'trigger-kind.webhook.label': 'Webhook',
+        'trigger-kind.webhook.description': 'Trigger from a POST request.',
+        'trigger-kind.feed.label': 'Feed',
+        'trigger-kind.feed.description': 'Run when a new item arrives in a feed.',
+        'trigger-kind.email.label': 'Email',
+        'trigger-kind.email.description': 'Run when an email is received.',
+        'trigger-kind.clear.label': 'Clear',
+        'trigger-kind.query-stub.message': 'Query editing is not yet available.',
+        'trigger-kind.email-note.message': 'Runs whenever a new email is received.',
+
+        'method.label': 'Method',
+        'port.label': 'Port',
+        'cron.placeholder': '0 0 * * *',
+        'feed.placeholder': 'Select a feed',
+        'enabled.label': 'Enabled',
+        'enabled.description': 'Turn this routine on or off.',
+        'add-trigger.label': 'Add trigger',
+        'add-trigger-first.message': 'Add a trigger to enable.',
+        'remove-trigger.label': 'Remove',
+        'select-action-first.message': 'Select an action first.',
+        'automation-companion.label': 'Routine',
+        'routine-runs.label': 'Runs',
+
+        'history.empty.message': 'No runs yet.',
+        'history.status.success.label': 'Success',
+        'history.status.failure.label': 'Failed',
+        'history.status.pending.label': 'Running',
+        'no-routines.message': 'No routines for this object.',
+        'routine-not-associated.message': 'Not yet associated with this object.',
+        'routine-detached.message': 'No longer associated with this object.',
+        'add-routine.label': 'Add routine',
+        'routine-actions.label': 'Routine actions',
+        'disabled.label': 'Disabled',
+        'delete.label': 'Delete',
+        'save.label': 'Save',
+        'cancel.label': 'Cancel',
+
+        'testing.title': 'Testing',
+        'force-run.label': 'Force run',
+        'reset-cursor.label': 'Reset feed cursor',
+        'reset-cursor-confirm.label': 'Confirm reset feed cursor',
+
+        'routine-verbose.label': 'Manage routines',
+        'routine.description': 'Manage where routines in this space run.',
+
+        'runtime.label': 'Runtime location',
+        'runtime.description': 'Determines where routines in this space run.',
+        'runtime.disabled.label': 'Disabled',
+        'runtime.local.label': 'Local',
+        'runtime.edge.label': 'EDGE (experimental)',
+      },
+    },
+  },
+] as const satisfies Resource[];

package/src/types/Routine.test.ts

@@ -0,0 +1,51 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { Instructions, Operation, Runnable, Trigger } from '@dxos/compute';
+import { Obj, Ref, Type } from '@dxos/echo';
+
+import { blank } from '../templates';
+import { isRunInstructions } from '../util';
+import * as Routine from './Routine';
+
+describe('Routine', () => {
+  test('make produces a typed Routine', ({ expect }) => {
+    const routine = Routine.make({ name: 'Test', triggers: [] });
+    expect(Routine.instanceOf(routine)).toBe(true);
+    expect(Obj.instanceOf(Routine.Routine, routine)).toBe(true);
+    expect(Type.getTypename(Routine.Routine)).toBe('org.dxos.type.routine');
+    expect(Obj.getLabel(routine)).toBe('Test');
+    expect(routine.triggers).toEqual([]);
+    expect(routine.spec).toBeUndefined();
+  });
+
+  test('Runnable seam is currently the Operation type', ({ expect }) => {
+    // MVP: Runnable === Operation. Widening this to a union is the documented next step.
+    expect(Runnable.Runnable).toBe(Operation.PersistentOperation);
+  });
+
+  test('make wires an instructions action so a single add yields a runnable routine', ({ expect }) => {
+    const instructions = Instructions.make({ name: 'Body', text: 'do something' });
+    const trigger = Trigger.make({ spec: Trigger.specTimer('0 9 * * *') });
+    const routine = Routine.make({ name: 'R', instructions, trigger });
+
+    // The routine owns the instructions, and the trigger dispatches RunInstructions with those instructions
+    // bound into the trigger input so no separate persistence step is needed.
+    expect(Routine.instructionsRef(routine)?.target?.id).toBe(instructions.id);
+    expect(routine.triggers[0]?.target?.id).toBe(trigger.id);
+    expect(isRunInstructions(trigger.runnable)).toBe(true);
+    const bound = trigger.input?.instructions;
+    expect(Ref.isRef(bound) ? bound.target?.id : undefined).toBe(instructions.id);
+  });
+
+  describe('blank template', () => {
+    test('is the default no-op template', ({ expect }) => {
+      expect(blank.id).toBe('org.dxos.routine.blank');
+      expect(blank.label).toBe('Blank');
+      expect(typeof blank.scaffold).toBe('function');
+    });
+  });
+});