@dxos/plugin-routine 0.0.0

package/src/types/Routine.ts

@@ -0,0 +1,144 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { Instructions, Runnable, Trigger } from '@dxos/compute';
+// Operation is imported so TypeScript can name Operation.PersistentOperation in the emitted .d.ts
+// (Runnable is an alias for Operation.PersistentOperation, so Routine's class type references it).
+// eslint-disable-next-line unused-imports/no-unused-imports
+import { Operation } from '@dxos/compute';
+import { Annotation, DXN, Obj, Ref, Type } from '@dxos/echo';
+import { LabelAnnotation } from '@dxos/echo/internal';
+
+import { runInstructionsRef } from '../util/run-instructions';
+
+const Kinds = ['runnable', 'instructions'] as const;
+export const Kind = Schema.Literal(...Kinds);
+export type Kind = (typeof Kinds)[number];
+
+const RunnableSpec = Schema.Struct({
+  kind: Schema.Literal('runnable'),
+  runnable: Ref.Ref(Runnable.Runnable),
+});
+
+const InstructionsSpec = Schema.Struct({
+  kind: Schema.Literal('instructions'),
+  instructions: Ref.Ref(Instructions.Instructions),
+});
+
+const RoutineSpec = Schema.Union(RunnableSpec, InstructionsSpec);
+
+/**
+ * User-facing routine: a thin aggregate of an action (`runnable`) and the triggers that fire it.
+ * App-level only — EDGE stays unaware of it (triggers point directly at the runnable).
+ */
+export class Routine extends Type.makeObject<Routine>(DXN.make('org.dxos.type.routine', '0.2.0'))(
+  Schema.Struct({
+    name: Schema.String.pipe(Schema.optional),
+    description: Schema.String.pipe(Schema.optional),
+
+    /**
+     * The action to run: either an Operation (`spec.runnable`, bound directly) or the routine's own owned
+     * Instructions (`spec.instructions`). For an Operation action the trigger's `runnable` points at this
+     * Operation. For an Instructions action `spec.instructions` is the owned Instructions object (the operation
+     * is implicitly the static RunInstructions, so no separate operation ref is stored), and the trigger's
+     * `runnable` is RunInstructions with this instructions bound as its input.
+     */
+    // TODO(burdon): Change to Array? Or handle that case with a ComputeGraph runnable.
+    spec: RoutineSpec.pipe(Schema.optional),
+
+    /**
+     * Explicit membership, bi-directional with `trigger.runnable → runnable`. Required (not derived by query)
+     * because the runnable may be a shared registry operation referenced by multiple automations, which would
+     * conflate triggers. MVP enforces length <= 1.
+     */
+    triggers: Schema.Array(Ref.Ref(Trigger.Trigger)),
+  }).pipe(
+    LabelAnnotation.set(['name']),
+    Annotation.IconAnnotation.set({ icon: 'ph--lightning--regular', hue: 'amber' }),
+  ),
+) {}
+
+/** Returns true when value is a Routine object. */
+export const instanceOf = (value: unknown): value is Routine => Obj.instanceOf(Routine, value);
+
+/**
+ * The owned Instructions ref of an instructions-action routine, or undefined for an operation action.
+ * Classification is explicit in `spec.kind`, so this needs no `.target` dereference; callers resolve the ref
+ * reactively (`useObject`) or asynchronously (`Database.load`) as appropriate.
+ */
+export const instructionsRef = (routine: Pick<Routine, 'spec'>): Ref.Ref<Instructions.Instructions> | undefined =>
+  routine.spec?.kind === 'instructions' ? routine.spec.instructions : undefined;
+
+/** The Operation (runnable) ref of an operation-action routine, or undefined for an instructions action. */
+export const runnableRef = (routine: Pick<Routine, 'spec'>): Ref.Ref<Runnable.Runnable> | undefined =>
+  routine.spec?.kind === 'runnable' ? routine.spec.runnable : undefined;
+
+/** Strip a stale `instructions` binding from a trigger input. */
+const withoutInstructions = (input: Record<string, unknown> | undefined): Record<string, unknown> | undefined => {
+  if (!input || !('instructions' in input)) {
+    return input;
+  }
+  const { instructions: _drop, ...rest } = input;
+  return rest;
+};
+
+/**
+ * Wire the routine's owned triggers to dispatch its current action (`spec`): an instructions action sets each
+ * trigger's `runnable` to RunInstructions with the owned instructions bound into `input`; an operation action
+ * binds the operation directly and drops any stale instructions binding. Call after the action (`spec`) changes
+ * so a trigger never keeps a binding for the previous action.
+ */
+export const wireTriggers = (routine: Routine): void => {
+  const instructions = instructionsRef(routine);
+  const fn = instructions ? runInstructionsRef() : runnableRef(routine);
+  for (const ref of routine.triggers) {
+    const trigger = ref.target;
+    if (!trigger) {
+      continue;
+    }
+    Obj.update(trigger, (trigger) => {
+      trigger.runnable = fn;
+      const base = withoutInstructions(trigger.input);
+      trigger.input = instructions ? { input: {}, ...base, instructions } : base;
+    });
+  }
+};
+
+/**
+ * Creates a fully-wired in-memory routine graph. `instructions` and `trigger` are optional extras beyond the
+ * schema fields: when provided they are parented under the routine and wired together (runnable, trigger
+ * runnable, the trigger's instructions input binding, and the `triggers` ref) so that a single `Database.add`
+ * cascades the whole graph. `triggers` defaults to `[]` so callers that supply a `trigger` need not provide it.
+ */
+export const make = ({
+  instructions,
+  trigger,
+  triggers = [],
+  ...props
+}: Omit<Obj.MakeProps<typeof Routine>, 'triggers'> & {
+  triggers?: ReadonlyArray<Ref.Ref<Trigger.Trigger>>;
+  instructions?: Instructions.Instructions;
+  trigger?: Trigger.Trigger;
+}): Routine => {
+  const routine = Obj.make(Routine, { ...props, triggers });
+  if (instructions) {
+    Obj.setParent(instructions, routine);
+    Obj.update(routine, (routine) => {
+      routine.spec = { kind: 'instructions', instructions: Ref.make(instructions) };
+    });
+  }
+  if (trigger) {
+    Obj.setParent(trigger, routine);
+    Obj.update(routine, (routine) => {
+      routine.triggers.push(Ref.make(trigger));
+    });
+    // Wire the trigger's `runnable`/`input` from the action (`spec`); preserves any template-provided input.
+    wireTriggers(routine);
+  }
+  return routine;
+};

package/src/types/RoutineCapabilities.ts

@@ -0,0 +1,51 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import type { Database, Obj } from '@dxos/echo';
+import type { DelegationStrategy } from '@dxos/functions-runtime';
+
+import * as Routine from './Routine';
+
+/**
+ * Optional supervisor strategy for the agent chat service. When contributed (by a plugin that knows
+ * the agent/plan model, e.g. plugin-assistant), the conversational agent delegates outstanding work
+ * to sub-agents and folds their results back into the conversation. Consumed by the AgentService
+ * LayerSpec; absent by default (a plain conversational agent).
+ */
+export const AgentDelegationStrategy = Capability.make<DelegationStrategy>(
+  'org.dxos.plugin.routine.capability.agentDelegationStrategy',
+);
+
+/**
+ * An automation template contributed by a plugin. The create dialog and the per-object "Automations"
+ * companion list contributed templates (`Capability.getAll(RoutineCapabilities.Template)`) and run the
+ * chosen template's `scaffold` to build the automation.
+ */
+export type Template = {
+  /** Stable id (e.g. 'org.dxos.routine.blank'). */
+  id: string;
+  /** Human-readable label shown in the picker. */
+  label: string;
+  /** Optional Phosphor icon name. */
+  icon?: string;
+  /**
+   * Whether this template applies to the given companion subject. The subject is the object whose
+   * "Automations" companion is open, or undefined in the global create dialog. Templates that need a
+   * specific subject (e.g. a feed-bearing Mailbox) gate themselves here. Defaults to always-applies.
+   */
+  appliesTo?: (subject?: Obj.Unknown) => boolean;
+  /**
+   * Build the routine as a fully-wired in-memory {@link Routine.Routine} graph — the routine plus its owned
+   * trigger and instructions, assembled by `Routine.make`. The create flow persists it with a single
+   * `Database.add` (which cascades the owned children); scaffold must NOT call `Database.add` itself.
+   * `Database.Service` may still be used for read-only lookups (e.g. loading a feed ref). `subject` is set
+   * when scaffolding from an object's companion.
+   */
+  scaffold: (ctx: { name?: string; subject?: Obj.Unknown }) => Effect.Effect<Routine.Routine, Error, Database.Service>;
+};
+
+export const Template = Capability.make<Template>('org.dxos.plugin.routine.capability.template');

package/src/types/RoutineOperation.ts

@@ -0,0 +1,104 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { Capability } from '@dxos/app-framework';
+import { Chat } from '@dxos/assistant-toolkit';
+import { Instructions, Operation } from '@dxos/compute';
+import { Database, DXN, Obj, Ref, Type } from '@dxos/echo';
+// Value-side `EID` import keeps TS declaration emit portable — `TriggerTemplate`
+// references `EID.Schema` and the inferred `CreateTriggerFromTemplate` type
+// otherwise needs a transitive `@dxos/keys` import that's hard for d.ts emit to surface.
+import { EID as _EchoURIReference } from '@dxos/keys';
+
+import { meta } from '#meta';
+
+import * as Routine from './Routine';
+import { TriggerTemplate } from './schema';
+export { _EchoURIReference };
+
+const makeKey = (name: string) => DXN.make(`${meta.profile.key}.operation.${name}`);
+
+export const CreateTriggerFromTemplate = Operation.make({
+  meta: {
+    key: makeKey('createTriggerFromTemplate'),
+    name: 'Create Trigger From Template',
+    icon: 'ph--lightning--regular',
+  },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    db: Database.Database,
+    template: TriggerTemplate,
+    enabled: Schema.optional(Schema.Boolean),
+    scriptName: Schema.optional(Schema.String),
+    input: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Any })),
+  }),
+  output: Schema.Void,
+});
+
+// The single creation entrypoint for every path (create dialog, companion, sidebar) so placement and
+// ownership are established in one place. Output mirrors `SpaceCapabilities.CreateObjectResult`.
+export const CreateRoutine = Operation.make({
+  meta: {
+    key: makeKey('createAutomation'),
+    name: 'Create Routine',
+    icon: 'ph--lightning--regular',
+  },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    db: Database.Database,
+    templateId: Schema.String,
+    name: Schema.optional(Schema.String),
+    subject: Schema.optional(Obj.Unknown),
+  }),
+  output: Schema.Struct({
+    id: Schema.String,
+    subject: Schema.Array(Schema.String),
+    object: Obj.Unknown,
+  }),
+});
+
+export const RunPromptInNewChat = Operation.make({
+  meta: {
+    key: makeKey('runPromptInNewChat'),
+    name: 'Run Prompt In New Chat',
+    icon: 'ph--chat-text--regular',
+  },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    db: Database.Database,
+    /** Context objects to bind to the new chat. */
+    objects: Schema.optional(Schema.Array(Obj.Unknown)),
+    /** Skill keys to look up and bind to the new chat. */
+    skills: Schema.optional(Schema.Array(Schema.String)),
+    /** Raw instructions or an existing Routine object reference. */
+    instructions: Schema.Union(Schema.String, Ref.Ref(Instructions.Instructions)),
+    /**
+     * When true, skips opening the chat: runs the Agent prompt operation against the new chat via the compute runtime (traced).
+     */
+    background: Schema.optional(Schema.Boolean),
+  }),
+  output: Schema.Struct({
+    object: Type.getSchema(Chat.Chat),
+  }),
+});
+
+// Runs a routine's `runnable` directly (bypassing its triggers). The runnable receives no input;
+// the trigger-driven path is what supplies event-mapped input, so manual runs target runnables that
+// need none.
+export const RunRoutine = Operation.make({
+  meta: {
+    key: makeKey('runAutomation'),
+    name: 'Run Routine',
+    icon: 'ph--play--regular',
+  },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    routine: Ref.Ref(Routine.Routine),
+  }),
+  output: Schema.Void,
+});

package/src/types/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './schema';
+
+export * as Routine from './Routine';
+export * as RoutineCapabilities from './RoutineCapabilities';
+export * as RoutineOperation from './RoutineOperation';

package/src/types/schema.ts

@@ -0,0 +1,31 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Database } from '@dxos/echo';
+
+import { meta } from '#meta';
+
+export const TriggerTemplate = Schema.Union(
+  Schema.Struct({ type: Schema.Literal('timer'), cron: Schema.String }),
+  Schema.Struct({ type: Schema.Literal('feed'), feed: Schema.Any }),
+);
+
+export namespace AutomationAction {
+  export class CreateTriggerFromTemplate extends Schema.TaggedClass<CreateTriggerFromTemplate>()(
+    `${meta.profile.key}.action.create-trigger-from-template`,
+    {
+      input: Schema.Struct({
+        db: Database.Database,
+        template: TriggerTemplate,
+        enabled: Schema.optional(Schema.Boolean),
+        // TODO(wittjosiah): Improve how this lookup is done.
+        scriptName: Schema.optional(Schema.String),
+        input: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Any })),
+      }),
+      output: Schema.Void,
+    },
+  ) {}
+}

package/src/util/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './routines-for-object';
+export * from './run-instructions';

package/src/util/routines-for-object.test.ts

@@ -0,0 +1,109 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import { Instructions, Trigger } from '@dxos/compute';
+import { type Database, DXN, Feed, Obj, Ref, Type } from '@dxos/echo';
+import { EffectEx } from '@dxos/effect';
+import { EID, URI } 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 { Routine } from '#types';
+
+import { connectedRoutinesQuery, routinesForObject } from './routines-for-object';
+
+// A minimal feed-annotated host (like a mailbox): an object holding a `feed` ref.
+const FeedHost = Type.makeObject(DXN.make('org.dxos.test.feedHost', '0.1.0'))(
+  Schema.Struct({
+    name: Schema.optional(Schema.String),
+    feed: Ref.Ref(Feed.Feed),
+  }),
+);
+
+const types = [Routine.Routine, Trigger.Trigger, Instructions.Instructions, Feed.Feed, FeedHost];
+
+const initSpace = async (harness: Awaited<ReturnType<typeof createComposerTestApp>>) => {
+  const { personalSpace } = await EffectEx.runAndForwardErrors(
+    initializeIdentity(harness.get(ClientCapabilities.Client)),
+  );
+  await harness.waitForEvent(ClientEvents.SpacesReady);
+  return personalSpace.db;
+};
+
+const connectedIds = (db: Database.Database, object: Obj.Unknown) =>
+  db
+    .query(connectedRoutinesQuery(object))
+    .run()
+    .then((routines) => routines.map((routine) => routine.id).sort());
+
+// Build a space-qualified ref like the RefField object picker does (from the entity's fully-qualified URI),
+// rather than the bare ref `Ref.make` produces — this is the encoding real triggers carry, and it exercises
+// the reverse-ref EID normalization that lets qualified refs match a space-less anchor.
+const qualifiedRef = (db: Database.Database, object: Obj.Unknown) =>
+  Ref.fromURI(URI.make(EID.make({ spaceId: db.spaceId, entityId: object.id })));
+
+describe('routines connected to an object', () => {
+  test('input-ref: trigger whose nested input references the object', async ({ expect }) => {
+    await using harness = await createComposerTestApp({ plugins: [ClientPlugin({ types })] });
+    const db = await initSpace(harness);
+
+    const target = db.add(Routine.make({ name: 'target', triggers: [] }));
+    const other = db.add(Routine.make({ name: 'other', triggers: [] }));
+    // The target ref is nested in the trigger's untyped `input` record, and is space-qualified like a
+    // picker-created ref.
+    const trigger = db.add(Trigger.make({ input: { subject: qualifiedRef(db, target) } }));
+    const owner = db.add(Routine.make({ name: 'owner', triggers: [Ref.make(trigger)] }));
+    await db.flush();
+
+    expect(routinesForObject(target, [owner, other]).map((routine) => routine.id)).toEqual([owner.id]);
+    expect(routinesForObject(other, [owner])).toEqual([]);
+
+    // Poll to absorb index latency; the query resolves via the reverse-ref index.
+    await expect.poll(() => connectedIds(db, target), { timeout: 5_000 }).toEqual([owner.id]);
+    await expect.poll(() => connectedIds(db, other), { timeout: 5_000 }).toEqual([]);
+  });
+
+  test("feed-ref: feed trigger bound to the object's feed", async ({ expect }) => {
+    await using harness = await createComposerTestApp({ plugins: [ClientPlugin({ types })] });
+    const db = await initSpace(harness);
+
+    const feed = db.add(Feed.make());
+    const host = db.add(Obj.make(FeedHost, { name: 'mailbox', feed: Ref.make(feed) }));
+    const other = db.add(Routine.make({ name: 'other', triggers: [] }));
+    // Picker-created feed refs are space-qualified (unlike `Trigger.specFeed`'s bare `Ref.make`); the host's
+    // own feed ref is bare (code-created). They must still match through the reverse-ref index.
+    const feedTrigger = db.add(Trigger.make({ spec: { kind: 'feed', feed: qualifiedRef(db, feed) } }));
+    const owner = db.add(Routine.make({ name: 'feed-owner', triggers: [Ref.make(feedTrigger)] }));
+    await db.flush();
+
+    expect(routinesForObject(host, [owner, other]).map((routine) => routine.id)).toEqual([owner.id]);
+
+    await expect.poll(() => connectedIds(db, host), { timeout: 5_000 }).toEqual([owner.id]);
+  });
+
+  test('instructions-ref: routine whose runnable instructions list the object in their `objects`', async ({
+    expect,
+  }) => {
+    await using harness = await createComposerTestApp({ plugins: [ClientPlugin({ types })] });
+    const db = await initSpace(harness);
+
+    const target = db.add(Routine.make({ name: 'target', triggers: [] }));
+    const other = db.add(Routine.make({ name: 'other', triggers: [] }));
+    // The routine's action is owned instructions that bind the object as a context object — the second
+    // connection path (O ← Instructions.objects ← Routine via spec.instructions), with no trigger involved.
+    const instructions = db.add(Instructions.make({ objects: [qualifiedRef(db, target)] }));
+    const owner = db.add(Routine.make({ name: 'owner', instructions }));
+    await db.flush();
+
+    expect(routinesForObject(target, [owner, other]).map((routine) => routine.id)).toEqual([owner.id]);
+    expect(routinesForObject(other, [owner])).toEqual([]);
+
+    await expect.poll(() => connectedIds(db, target), { timeout: 5_000 }).toEqual([owner.id]);
+    await expect.poll(() => connectedIds(db, other), { timeout: 5_000 }).toEqual([]);
+  });
+});

package/src/util/routines-for-object.ts

@@ -0,0 +1,89 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Instructions, Trigger } from '@dxos/compute';
+import { Filter, Obj, Query, Ref } from '@dxos/echo';
+
+import { Routine } from '#types';
+
+/**
+ * Reactive query for all routines connected to an object O, via two structural paths:
+ *
+ * 1. **Trigger path** (two hops): O is referenced by a Trigger (via `input` or `spec.feed`), and that
+ *    Trigger is referenced by a Routine's `triggers` array.
+ * 2. **Instructions path** (two hops): O is listed in an Instructions' `objects` context array, and those
+ *    Instructions are the Routine's action (`spec.instructions`). Both hops traverse `Ref` fields, so they are
+ *    fully queryable — no JavaScript parent-symbol traversal needed.
+ *
+ * ECHO's reverse-ref index is structural — it tracks every `Ref` regardless of schema path, including
+ * nested untyped records and union fields — so all variants are covered.
+ */
+export const connectedRoutinesQuery = (object: Obj.Unknown): Query.Query<Routine.Routine> => {
+  // Trigger path: O ← Trigger (any ref path, incl. nested `input`) ← Routine.triggers.
+  const byInput = Query.select(Filter.id(object.id)).referencedBy(Trigger.Trigger);
+  // Feed variant: O's feed ← Trigger.spec.feed ← Routine.triggers.
+  // `.reference('feed')` is empty for objects without a feed prop, so this adds nothing for non-feed objects.
+  const byFeed = Query.select(Filter.id(object.id)).reference('feed').referencedBy(Trigger.Trigger);
+  const byTrigger = Query.all(byInput, byFeed).referencedBy(Routine.Routine, 'triggers');
+
+  // Instructions path: O ← Instructions.objects ← Routine (via `spec.instructions`). The second hop drops the
+  // property key: the instructions ref is nested in the `spec` union, and the reverse-ref index is structural,
+  // so a keyless `referencedBy` matches it (a routine only references its own owned instructions here).
+  const byInstructions = Query.select(Filter.id(object.id))
+    .referencedBy(Instructions.Instructions, 'objects')
+    .referencedBy(Routine.Routine);
+
+  return Query.all(byTrigger, byInstructions);
+};
+
+/**
+ * Pure predicate equivalent of {@link connectedRoutinesQuery}, over a pre-queried list of routines.
+ * Kept for unit tests (asserting the query and predicate agree) and the deferred quick-association check.
+ */
+export const routinesForObject = (object: Obj.Unknown, routines: Routine.Routine[]): Routine.Routine[] =>
+  routines.filter((routine) => routineReferencesObject(routine, object));
+
+export const routineReferencesObject = (routine: Routine.Routine, object: Obj.Unknown): boolean =>
+  referencesViaTrigger(routine, object) || referencesViaInstructions(routine, object);
+
+/** Trigger path: a trigger's `input` references O, or a feed trigger is bound to O's feed. */
+const referencesViaTrigger = (routine: Routine.Routine, object: Obj.Unknown): boolean => {
+  const objectFeedId = getFeedId(object);
+  return routine.triggers.some((ref) => {
+    const trigger = ref.target;
+    if (!Obj.instanceOf(Trigger.Trigger, trigger)) {
+      return false;
+    }
+
+    if (trigger.spec?.kind === 'feed' && objectFeedId && trigger.spec.feed?.target?.id === objectFeedId) {
+      return true;
+    }
+
+    return trigger.input != null && referencesId(trigger.input, object.id);
+  });
+};
+
+/** Instructions path: the routine's owned instructions list O in their `objects` context array. */
+const referencesViaInstructions = (routine: Routine.Routine, object: Obj.Unknown): boolean =>
+  Routine.instructionsRef(routine)?.target?.objects?.some((ref) => ref.target?.id === object.id) ?? false;
+
+/** The feed id a feed-annotated object points at (e.g. `mailbox.feed`), if any. */
+const getFeedId = (object: Obj.Unknown): string | undefined => {
+  const feedRef = (object as { feed?: Ref.Ref<unknown> }).feed;
+  return Ref.isRef(feedRef) ? feedRef.target?.id : undefined;
+};
+
+/** Recursively scan a value for a Ref whose target is the given object id. */
+const referencesId = (value: unknown, id: string): boolean => {
+  if (Ref.isRef(value)) {
+    return value.target?.id === id;
+  }
+  if (Array.isArray(value)) {
+    return value.some((entry) => referencesId(entry, id));
+  }
+  if (value && typeof value === 'object') {
+    return Object.values(value).some((entry) => referencesId(entry, id));
+  }
+  return false;
+};

package/src/util/run-instructions.test.ts

@@ -0,0 +1,23 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { RunInstructions } from '@dxos/assistant-toolkit';
+import { Ref, URI } from '@dxos/echo';
+
+import { isRunInstructions, runInstructionsRef } from './run-instructions';
+
+describe('RunInstructions registry reference', () => {
+  test('runInstructionsRef targets the RunInstructions registry DXN', ({ expect }) => {
+    const ref = runInstructionsRef();
+    expect(ref.uri).toBe(RunInstructions.meta.key);
+    expect(isRunInstructions(ref)).toBe(true);
+  });
+
+  test('isRunInstructions rejects other refs and non-refs', ({ expect }) => {
+    expect(isRunInstructions(undefined)).toBe(false);
+    expect(isRunInstructions(Ref.fromURI(URI.make('dxn:org.dxos.test.otherOperation')))).toBe(false);
+  });
+});

package/src/util/run-instructions.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { RunInstructions } from '@dxos/assistant-toolkit';
+import { Ref } from '@dxos/echo';
+
+/** A ref to the shared RunInstructions operation in the registry (resolved via the registry, not the database). */
+export const runInstructionsRef = () => Ref.fromURI(RunInstructions.meta.key);
+
+/** Whether a trigger's `function` ref targets the registry RunInstructions operation (i.e. an instructions action). */
+export const isRunInstructions = (fn: unknown): boolean => Ref.isRef(fn) && fn.uri === RunInstructions.meta.key;

package/src/vite-env.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+
+//
+// Copyright 2026 DXOS.org
+//
+
+declare module '*.mdl?raw' {
+  const content: string;
+  export default content;
+}