@dxos/plugin-routine 0.10.0 → 0.11.0

package/src/operations/run-routine.test.ts

@@ -0,0 +1,150 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Atom, Registry } from '@effect-atom/atom';
+import { describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Schema from 'effect/Schema';
+
+import { AssistantTestLayer } from '@dxos/agent-runtime/testing';
+import { Capability, CapabilityManager } from '@dxos/app-framework';
+import { Operation, OperationHandlerSet, Routine, Trigger } from '@dxos/compute';
+import { Database, DXN, Ref } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+
+import { RoutineOperation } from '../types';
+import { makeRoutine } from '../util';
+import RunRoutineHandler from './run-routine';
+
+/** Captures the input each run receives so the test can assert on it after the invocation. */
+const received: unknown[] = [];
+
+/** Trigger ids the monitor was asked to invoke — the seam a `remote` trigger must reach instead of running here. */
+const monitorInvocations: string[] = [];
+
+/** Stands in for the aggregate monitor, whose real implementation routes `remote` triggers to EDGE over HTTP. */
+const TestMonitor = Layer.succeed(Trigger.TriggerMonitorService, {
+  triggers: Atom.make<readonly Trigger.State[]>([]),
+  localDispatcherEnabled: false,
+  invokeTrigger: ({ trigger }) => Effect.sync(() => void monitorInvocations.push(trigger.id)),
+});
+
+/**
+ * Stand-in for a connector's sync operation: like `InboxOperation.GoogleMailSync` it destructures a
+ * required input, so a run that supplies none throws before the handler body.
+ */
+const TestRunnable = Operation.make({
+  meta: { key: DXN.make('org.dxos.test.runnable'), name: 'Test Runnable' },
+  input: Schema.Struct({ label: Schema.Any }),
+  output: Schema.Void,
+});
+
+const TestLayer = AssistantTestLayer({
+  operationHandlers: OperationHandlerSet.make(
+    RunRoutineHandler,
+    TestRunnable.pipe(
+      Operation.withHandler(({ label }) => {
+        received.push(label);
+        return Effect.void;
+      }),
+    ),
+  ),
+  types: [Routine.Routine, Trigger.Trigger, Operation.PersistentOperation],
+  disableLlmMemoization: true,
+  // `RunRoutine` declares `Capability.Service`; an empty manager discharges it (the handler never reads it).
+  extraServices: Layer.mergeAll(
+    Layer.succeed(Capability.Service, CapabilityManager.make({ registry: Registry.make() })),
+    TestMonitor,
+  ),
+});
+
+describe('RunRoutine', () => {
+  it.effect(
+    'passes the trigger input to the runnable',
+    Effect.fnUntraced(
+      function* ({ expect }) {
+        received.length = 0;
+        const { routine } = yield* addRoutine({ label: 'from-trigger' });
+
+        yield* Operation.invoke(RoutineOperation.RunRoutine, { routine: Ref.make(routine) });
+
+        expect(received).toEqual(['from-trigger']);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.effect(
+    'resolves an event template against the synthetic run event',
+    Effect.fnUntraced(
+      function* ({ expect }) {
+        received.length = 0;
+        const { routine } = yield* addRoutine({ label: '{{event.tick}}' });
+
+        yield* Operation.invoke(RoutineOperation.RunRoutine, { routine: Ref.make(routine) });
+
+        expect(received).toHaveLength(1);
+        expect(received[0]).toBeTypeOf('number');
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.effect(
+    'routes a remote trigger to the monitor instead of running the runnable locally',
+    Effect.fnUntraced(
+      function* ({ expect }) {
+        received.length = 0;
+        monitorInvocations.length = 0;
+        const { routine, trigger } = yield* addRoutine({ label: 'on-edge' }, true);
+
+        yield* Operation.invoke(RoutineOperation.RunRoutine, { routine: Ref.make(routine) });
+
+        // The monitor sends it to the EDGE dispatcher; nothing runs in this process.
+        expect(monitorInvocations).toEqual([trigger.id]);
+        expect(received).toEqual([]);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.effect(
+    'runs a local trigger in-process without touching the monitor',
+    Effect.fnUntraced(
+      function* ({ expect }) {
+        received.length = 0;
+        monitorInvocations.length = 0;
+        const { routine } = yield* addRoutine({ label: 'on-client' });
+
+        yield* Operation.invoke(RoutineOperation.RunRoutine, { routine: Ref.make(routine) });
+
+        expect(received).toEqual(['on-client']);
+        expect(monitorInvocations).toEqual([]);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});
+
+/**
+ * A routine whose action is `TestRunnable`, with the runnable's input carried on its timer trigger.
+ * Returns the trigger alongside so assertions can name its id without re-deriving it from the ref.
+ */
+const addRoutine = Effect.fnUntraced(function* (input: Record<string, unknown>, remote?: boolean) {
+  const operation = yield* Database.add(Operation.serialize(TestRunnable));
+  const trigger = Trigger.make({ enabled: true, remote, spec: Trigger.specTimer('*/10 * * * *'), input });
+  const routine = makeRoutine({
+    name: 'Test',
+    spec: { kind: 'runnable', runnable: Ref.make(operation) },
+    trigger,
+  });
+  yield* Database.add(routine);
+  yield* Database.flush();
+  return { routine, trigger };
+});

package/src/operations/run-routine.ts

@@ -5,7 +5,8 @@
 import * as Effect from 'effect/Effect';
 
 import { RunInstructions } from '@dxos/assistant-toolkit';
-import { Operation } from '@dxos/compute';
+import { Operation, Trigger } from '@dxos/compute';
+import { createInvocationPayload } from '@dxos/compute-runtime';
 import { Database, Obj } from '@dxos/echo';
 import { invariant } from '@dxos/invariant';
 
@@ -20,6 +21,18 @@ const handler: Operation.WithHandler<typeof RoutineOperation.RunRoutine> = Routi
       const routineObj = yield* Database.load(routine);
       const db = Obj.getDatabase(routineObj);
       invariant(db, 'Routine is not attached to a database.');
+      // Triggers, not routines, carry the runnable's input binding (e.g. a sync routine's `binding`
+      // cursor) and the `remote` flag, so a manual run goes through the first trigger — the one it is
+      // also attributed to.
+      const trigger = routineObj.triggers[0] ? yield* Database.load(routineObj.triggers[0]) : undefined;
+
+      // An edge routine is registered only on the EDGE dispatcher, so running it means force-running that
+      // trigger over HTTP; invoking the runnable here would silently run it on the client instead.
+      if (trigger?.remote === true) {
+        const monitor = yield* Trigger.TriggerMonitorService;
+        yield* monitor.invokeTrigger({ trigger, event: { tick: Date.now() } });
+        return;
+      }
 
       // The action kind is explicit in `spec`; dispatch by kind rather than dereferencing to classify.
       const spec = routineObj.spec;
@@ -37,7 +50,10 @@ const handler: Operation.WithHandler<typeof RoutineOperation.RunRoutine> = Routi
       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));
+      // Built by the dispatcher's own payload builder against a synthetic tick, so a manual run resolves
+      // `{{event.*}}`/`{{trigger.*}}` templates exactly as a scheduled fire would.
+      const input = trigger ? createInvocationPayload(trigger, { tick: Date.now() }) : undefined;
+      yield* Operation.invoke(Operation.deserialize(operation), input);
     }),
   ),
 );

package/src/paths.ts

@@ -2,17 +2,17 @@
 // Copyright 2026 DXOS.org
 //
 
-import { Paths } from '@dxos/app-toolkit';
+import { GraphPath } from '@dxos/app-toolkit';
+import { Routine } from '@dxos/compute';
 
 import { meta } from '#meta';
-import { Routine } from '#types';
 
-const { getSectionPath: getRoutinesPath } = Paths.createTypeSectionPaths(Routine.Routine, {
-  groupId: Paths.GroupSegments.ai,
+const { getSectionPath: getRoutinesPath } = GraphPath.createTypeSectionPaths(Routine.Routine, {
+  groupId: GraphPath.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`);
+  GraphPath.getSpacePath(spaceId, 'settings', `${meta.profile.key}.routines`);
 
 export { getRoutinesPath };

package/src/templates/index.ts

@@ -9,7 +9,9 @@ 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';
+import { RoutineCapabilities } from '#types';
+
+import { makeRoutine } from '../util';
 
 /**
  * Blank template: an instructions-action routine draft with an empty trigger; the action kind, schedule, and
@@ -18,12 +20,12 @@ import { Routine, type RoutineCapabilities } from '#types';
  * (no subject) starts with bare instructions.
  */
 export const blank: RoutineCapabilities.Template = {
-  id: 'org.dxos.routine.blank',
+  id: RoutineCapabilities.BlankTemplateId,
   label: 'Blank',
   icon: 'ph--lightning--regular',
   scaffold: ({ name, subject }) =>
     Effect.succeed(
-      Routine.make({
+      makeRoutine({
         name,
         instructions: Instructions.make({
           skills: subject ? skillRefsForObject(subject) : [],

package/src/translations.ts

@@ -2,13 +2,13 @@
 // Copyright 2023 DXOS.org
 //
 
+import { Routine } from '@dxos/compute';
 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,
@@ -75,6 +75,8 @@ export const translations: Resource[] = [
         '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.direct.label': 'Direct',
+        'trigger-kind.direct.description': 'Run only when invoked directly.',
         '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.',
@@ -114,11 +116,8 @@ export const translations: Resource[] = [
         '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)',
+        'runtime.label': 'Enable triggers',
+        'runtime.description': "Run this space's triggers. Individual triggers can be routed to the edge.",
       },
     },
   },

package/src/types/RoutineCapabilities.ts

@@ -4,11 +4,10 @@
 
 import type * as Effect from 'effect/Effect';
 
+import type { DelegationStrategy } from '@dxos/agent-runtime';
 import { Capability } from '@dxos/app-framework';
+import type { Routine } from '@dxos/compute';
 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
@@ -20,6 +19,13 @@ export const AgentDelegationStrategy = Capability.make<DelegationStrategy>(
   'org.dxos.plugin.routine.capability.agentDelegationStrategy',
 );
 
+/**
+ * Id of the built-in blank template. Declared here (rather than on the template itself) so callers that
+ * scaffold a routine without the picker — e.g. a project's toolbar — can name it without importing the
+ * template module.
+ */
+export const BlankTemplateId = 'org.dxos.routine.blank';
+
 /**
  * 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
@@ -40,7 +46,7 @@ export type Template = {
   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
+   * trigger and instructions, assembled by `makeRoutine`. 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.

package/src/types/RoutineOperation.ts

@@ -8,7 +8,7 @@ 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 { Instructions, Operation, Routine, Trigger } 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
@@ -17,7 +17,6 @@ import { EID as _EchoURIReference } from '@dxos/keys';
 
 import { meta } from '#meta';
 
-import * as Routine from './Routine';
 import { TriggerTemplate } from './schema';
 export { _EchoURIReference };
 
@@ -87,16 +86,18 @@ export const RunPromptInNewChat = Operation.make({
   }),
 });
 
-// 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.
+// Runs a routine's action now, routed by its first trigger — that is where both the runnable's input
+// (e.g. a sync routine's binding cursor) and the `remote` flag live. A `remote` trigger force-runs on the
+// EDGE dispatcher over HTTP, since that is the only runtime it is registered on; a local one runs
+// in-process. Without the trigger a manual run would invoke an input-taking runnable with nothing, and
+// would silently run an edge routine on the client.
 export const RunRoutine = Operation.make({
   meta: {
     key: makeKey('runAutomation'),
     name: 'Run Routine',
     icon: 'ph--play--regular',
   },
-  services: [Capability.Service],
+  services: [Capability.Service, Trigger.TriggerMonitorService],
   input: Schema.Struct({
     routine: Ref.Ref(Routine.Routine),
   }),

package/src/types/index.ts

@@ -4,6 +4,5 @@
 
 export * from './schema';
 
-export * as Routine from './Routine';
 export * as RoutineCapabilities from './RoutineCapabilities';
 export * as RoutineOperation from './RoutineOperation';

package/src/util/index.ts

@@ -4,3 +4,4 @@
 
 export * from './routines-for-object';
 export * from './run-instructions';
+export * from './wire';

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

@@ -5,17 +5,17 @@
 import * as Schema from 'effect/Schema';
 import { describe, test } from 'vitest';
 
-import { Instructions, Trigger } from '@dxos/compute';
+import { Instructions, Routine, 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 { AccessToken, Cursor } from '@dxos/link';
 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';
+import { makeRoutine } from './wire';
 
 // 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'))(
@@ -25,7 +25,15 @@ const FeedHost = Type.makeObject(DXN.make('org.dxos.test.feedHost', '0.1.0'))(
   }),
 );
 
-const types = [Routine.Routine, Trigger.Trigger, Instructions.Instructions, Feed.Feed, FeedHost];
+const types = [
+  Routine.Routine,
+  Trigger.Trigger,
+  Instructions.Instructions,
+  Feed.Feed,
+  FeedHost,
+  Cursor.Cursor,
+  AccessToken.AccessToken,
+];
 
 const initSpace = async (harness: Awaited<ReturnType<typeof createComposerTestApp>>) => {
   const { personalSpace } = await EffectEx.runAndForwardErrors(
@@ -68,6 +76,30 @@ describe('routines connected to an object', () => {
     await expect.poll(() => connectedIds(db, other), { timeout: 5_000 }).toEqual([]);
   });
 
+  test('cursor-ref: trigger bound (via `binding`) to a Cursor whose `spec.target` is 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: [] }));
+    // A sync trigger references its target only indirectly: `input.binding` → Cursor → `spec.target` → target.
+    const token = db.add(AccessToken.make({ source: 'github.com', token: 'tok' }));
+    const cursor = db.add(Cursor.makeExternal({ source: Ref.make(token), target: qualifiedRef(db, target) }));
+    const trigger = db.add(
+      Trigger.make({ spec: Trigger.specTimer('*/10 * * * *'), input: { binding: qualifiedRef(db, cursor) } }),
+    );
+    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([]);
+
+    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);
@@ -97,7 +129,7 @@ describe('routines connected to an object', () => {
     // 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 }));
+    const owner = db.add(makeRoutine({ name: 'owner', instructions }));
     await db.flush();
 
     expect(routinesForObject(target, [owner, other]).map((routine) => routine.id)).toEqual([owner.id]);

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

@@ -2,17 +2,19 @@
 // Copyright 2026 DXOS.org
 //
 
-import { Instructions, Trigger } from '@dxos/compute';
+import { Instructions, Routine, Trigger } from '@dxos/compute';
 import { Filter, Obj, Query, Ref } from '@dxos/echo';
-
-import { Routine } from '#types';
+import { Cursor } from '@dxos/link';
 
 /**
- * Reactive query for all routines connected to an object O, via two structural paths:
+ * Reactive query for all routines connected to an object O, via three 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
+ * 2. **Cursor path** (three hops): a sync Trigger doesn't reference its synced target directly — its `binding`
+ *    references an external-sync {@link Cursor}, and the Cursor's `spec.target` references O. So O is reached
+ *    one hop further out (O ← Cursor ← Trigger ← Routine), keeping the target ref out of the operation input.
+ * 3. **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.
  *
@@ -25,7 +27,9 @@ export const connectedRoutinesQuery = (object: Obj.Unknown): Query.Query<Routine
   // 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');
+  // Cursor variant: O ← Cursor (spec.target) ← Trigger (input.binding) ← Routine.triggers.
+  const byCursor = Query.select(Filter.id(object.id)).referencedBy(Cursor.Cursor).referencedBy(Trigger.Trigger);
+  const byTrigger = Query.all(byInput, byFeed, byCursor).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,
@@ -47,7 +51,10 @@ export const routinesForObject = (object: Obj.Unknown, routines: Routine.Routine
 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. */
+/**
+ * Trigger path: a trigger's `input` references O (directly, or via a bound {@link Cursor} whose `spec.target`
+ * is 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) => {
@@ -60,7 +67,10 @@ const referencesViaTrigger = (routine: Routine.Routine, object: Obj.Unknown): bo
       return true;
     }
 
-    return trigger.input != null && referencesId(trigger.input, object.id);
+    if (trigger.input == null) {
+      return false;
+    }
+    return referencesId(trigger.input, object.id) || referencesViaCursor(trigger.input, object.id);
   });
 };
 
@@ -74,6 +84,21 @@ const getFeedId = (object: Obj.Unknown): string | undefined => {
   return Ref.isRef(feedRef) ? feedRef.target?.id : undefined;
 };
 
+/** Recursively scan a value for a Cursor ref (e.g. a sync trigger's `binding`) that itself references O. */
+const referencesViaCursor = (value: unknown, id: string): boolean => {
+  if (Ref.isRef(value)) {
+    const cursor = value.target;
+    return Obj.instanceOf(Cursor.Cursor, cursor) && referencesId(cursor.spec, id);
+  }
+  if (Array.isArray(value)) {
+    return value.some((entry) => referencesViaCursor(entry, id));
+  }
+  if (value && typeof value === 'object') {
+    return Object.values(value).some((entry) => referencesViaCursor(entry, id));
+  }
+  return false;
+};
+
 /** 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)) {

package/src/util/wire.test.ts

@@ -0,0 +1,77 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { Instructions, Operation, Routine, Runnable, Trigger } from '@dxos/compute';
+import { Obj, Ref } from '@dxos/echo';
+
+import { blank } from '../templates';
+import { isRunInstructions, runInstructionsRef } from './run-instructions';
+import { makeRoutine } from './wire';
+
+describe('wire', () => {
+  test('makeRoutine produces a typed Routine', ({ expect }) => {
+    const routine = makeRoutine({ name: 'Test', triggers: [] });
+    expect(Routine.instanceOf(routine)).toBe(true);
+    expect(Obj.instanceOf(Routine.Routine, routine)).toBe(true);
+    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('makeRoutine 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 = makeRoutine({ 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);
+    // A trigger with no explicit `remote` flag runs locally.
+    expect(trigger.remote).toBeUndefined();
+  });
+
+  test('makeRoutine preserves an explicit trigger remote override', ({ expect }) => {
+    const trigger = Trigger.make({ remote: true });
+    const routine = makeRoutine({ name: 'R', trigger });
+    expect(routine.triggers[0]?.target?.remote).toBe(true);
+  });
+
+  test('makeRoutine wires triggers supplied via the `triggers` array', ({ expect }) => {
+    const instructions = Instructions.make({ name: 'Body', text: 'do something' });
+    const trigger = Trigger.make({ spec: Trigger.specTimer('0 9 * * *') });
+    const routine = makeRoutine({ name: 'R', instructions, triggers: [Ref.make(trigger)] });
+    expect(isRunInstructions(trigger.runnable)).toBe(true);
+    const bound = trigger.input?.instructions;
+    expect(Ref.isRef(bound) ? bound.target?.id : undefined).toBe(instructions.id);
+  });
+
+  test('makeRoutine leaves pre-set trigger bindings alone when there is no action', ({ expect }) => {
+    const trigger = Trigger.make({});
+    const preset = runInstructionsRef();
+    Obj.update(trigger, (trigger) => {
+      trigger.runnable = preset;
+    });
+    makeRoutine({ name: 'R', trigger });
+    expect(trigger.runnable?.uri).toBe(preset.uri);
+  });
+
+  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');
+    });
+  });
+});