@dxos/plugin-routine 0.0.0

package/src/commands/trigger/util.ts

@@ -0,0 +1,412 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Prompt from '@effect/cli/Prompt';
+import * as Ansi from '@effect/printer-ansi/Ansi';
+import * as Console from 'effect/Console';
+import * as Effect from 'effect/Effect';
+import * as Match from 'effect/Match';
+import * as Option from 'effect/Option';
+import type * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { FormBuilder } from '@dxos/cli-util';
+import { Operation, Trigger } from '@dxos/compute';
+// eslint-disable-next-line unused-imports/no-unused-imports
+import { Annotation, Database, Entity, Feed, Filter, Obj, Query, type QueryAST, Ref, Scope, Type } from '@dxos/echo';
+import { SchemaEx } from '@dxos/effect';
+import { DXN } from '@dxos/keys';
+import { FeedAnnotation } from '@dxos/schema';
+
+export type TriggerRemoteStatus = 'available' | 'not available' | 'n/a';
+
+/**
+ * Determines the remote status of a trigger.
+ * Only timer/cron triggers can be checked for remote availability.
+ */
+export const getTriggerRemoteStatus = (trigger: Trigger.Trigger, remoteCronIds: string[]): TriggerRemoteStatus => {
+  if (trigger.spec?.kind !== 'timer') {
+    return 'n/a';
+  }
+  return remoteCronIds.includes(trigger.id) ? 'available' : 'not available';
+};
+
+/**
+ * Pretty prints a trigger with ANSI colors.
+ */
+export const printTrigger = Effect.fn(function* (trigger: Trigger.Trigger, remoteStatus?: TriggerRemoteStatus) {
+  const fn = trigger.runnable && (yield* Database.load(trigger.runnable));
+
+  return FormBuilder.make({
+    title: trigger.id,
+  }).pipe(
+    FormBuilder.set(
+      'status',
+      trigger.enabled ? 'enabled' : 'disabled',
+      trigger.enabled ? Ansi.green : Ansi.blackBright,
+    ),
+    FormBuilder.option('kind', Option.fromNullable(trigger.spec?.kind)),
+    FormBuilder.option(
+      'remote',
+      Option.fromNullable(remoteStatus),
+      Match.type<TriggerRemoteStatus>().pipe(
+        Match.withReturnType<Ansi.Ansi>(),
+        Match.when('available', () => Ansi.green),
+        Match.when('not available', () => Ansi.yellow),
+        Match.when('n/a', () => Ansi.blackBright),
+        Match.exhaustive,
+      ),
+    ),
+    FormBuilder.when(
+      fn,
+      FormBuilder.nest(
+        'function',
+        FormBuilder.make().pipe(
+          FormBuilder.set('key', Obj.getMeta(fn as Operation.PersistentOperation).key),
+          FormBuilder.set('dxn', Obj.getURI(fn as Obj.Unknown)),
+        ),
+      ),
+    ),
+    FormBuilder.nestedOption('spec', Option.fromNullable(trigger.spec).pipe(Option.map(printSpec))),
+    FormBuilder.build,
+  );
+});
+
+const printSpec = <T extends Trigger.Spec>(spec: T): FormBuilder.FormBuilder => {
+  switch (spec.kind) {
+    case 'timer':
+      return printTimer(spec);
+    case 'subscription':
+      return printSubscription(spec);
+    case 'webhook':
+      return printWebhook(spec);
+    case 'feed':
+      return printFeed(spec);
+    default:
+      return FormBuilder.make({}).pipe(FormBuilder.set('unknown', 'Unknown spec type'));
+  }
+};
+
+const printTimer = (spec: Trigger.TimerSpec) => FormBuilder.make({}).pipe(FormBuilder.set('cron', spec.cron));
+
+const printSubscription = (spec: Trigger.SubscriptionSpec) =>
+  FormBuilder.make({}).pipe(FormBuilder.set('query', spec.query?.raw ?? '[Query AST]'));
+
+const printWebhook = (spec: Trigger.WebhookSpec) =>
+  FormBuilder.make({}).pipe(FormBuilder.set('method', spec.method), FormBuilder.set('port', spec.port));
+
+const printFeed = (spec: Trigger.FeedSpec) =>
+  FormBuilder.make({}).pipe(FormBuilder.set('feed', spec.feed ? spec.feed.uri.toString() : '(none)'));
+
+/**
+ * Prompts for input values based on an Effect schema.
+ * First shows a multi-select to choose which properties to specify,
+ * then prompts for values of the selected properties.
+ * Required properties are automatically included and cannot be unselected.
+ * @param schema - The Effect schema to prompt for
+ * @param defaults - Optional default values to use as initial values and pre-select optional properties
+ */
+export const promptForSchemaInput = Effect.fn(function* (
+  schema: Schema.Schema.AnyNoContext | undefined,
+  defaults?: Record<string, any> | undefined,
+) {
+  if (!schema) {
+    return {};
+  }
+
+  const ast = schema.ast;
+
+  // Check if it's a struct/object type
+  if (!SchemaAST.isTypeLiteral(ast)) {
+    return {};
+  }
+
+  const properties = SchemaEx.getProperties(ast);
+  if (properties.length === 0) {
+    return {};
+  }
+
+  // Separate required and optional properties
+  const requiredProperties: typeof properties = [];
+  const optionalProperties: typeof properties = [];
+
+  for (const prop of properties) {
+    if (prop.isOptional) {
+      optionalProperties.push(prop);
+    } else {
+      requiredProperties.push(prop);
+    }
+  }
+
+  // Build property info
+  const propertyInfo = properties.map((prop) => {
+    const key = prop.name.toString();
+    return {
+      prop,
+      key,
+      isRequired: !prop.isOptional,
+    };
+  });
+
+  // Multi-select: show all properties and let user select which optional ones to include
+  const selectedKeys = new Set<string>();
+
+  // Required properties are automatically selected
+  for (const info of propertyInfo) {
+    if (info.isRequired) {
+      selectedKeys.add(info.key);
+    }
+  }
+
+  // Show required properties that will be automatically included
+  if (requiredProperties.length > 0) {
+    const requiredNames = requiredProperties.map((p) => {
+      const info = propertyInfo.find((i) => i.prop === p);
+      return info?.key ?? p.name.toString();
+    });
+    yield* Console.log(`Required properties (will be included): ${requiredNames.join(', ')}`);
+  }
+
+  // For optional properties, use multi-select to choose which ones to include
+  if (optionalProperties.length > 0) {
+    const optionalInfo = propertyInfo.filter((info) => !info.isRequired);
+    const choices = optionalInfo.map((info) => {
+      const hasDefault = defaults?.[info.key] !== undefined;
+      const defaultText = hasDefault ? ` (current: ${JSON.stringify(defaults[info.key])})` : '';
+      return {
+        title: `${info.key}${defaultText}`,
+        value: info.key,
+        description: hasDefault ? 'Has default value' : undefined,
+      };
+    });
+
+    const selected = yield* Prompt.multiSelect({
+      message: 'Select optional properties to include:',
+      choices,
+    });
+
+    // Add selected optional properties to selectedKeys
+    for (const key of selected) {
+      selectedKeys.add(String(key));
+    }
+  }
+
+  // If no properties selected (shouldn't happen if there are required ones), return empty
+  if (selectedKeys.size === 0) {
+    return {};
+  }
+
+  // Prompt for values of selected properties
+  const inputObj: Record<string, any> = {};
+
+  for (const info of propertyInfo) {
+    if (!selectedKeys.has(info.key)) {
+      continue;
+    }
+
+    const key = info.key;
+    const propType = info.prop.type;
+    const schemaDefault = Option.getOrUndefined(SchemaAST.getDefaultAnnotation(propType));
+    const defaultValue = defaults?.[key] ?? schemaDefault;
+
+    if (SchemaAST.isBooleanKeyword(propType)) {
+      const initialValue =
+        typeof defaultValue === 'boolean' ? defaultValue : typeof schemaDefault === 'boolean' ? schemaDefault : false;
+      const value = yield* Prompt.confirm({
+        message: `${info.key}${defaults?.[key] !== undefined ? ` (current: ${defaults[key]})` : ''}:`,
+        initial: initialValue,
+      });
+      inputObj[key] = value;
+    } else if (SchemaAST.isNumberKeyword(propType)) {
+      const currentValue = typeof defaultValue === 'number' ? String(defaultValue) : '';
+      const valueStr = yield* Prompt.text({
+        message: `${info.key}${currentValue ? ` (current: ${currentValue}, press Enter to keep)` : ''}:`,
+      }).pipe(Prompt.run);
+      inputObj[key] = valueStr === '' && defaultValue !== undefined ? defaultValue : parseFloat(valueStr) || 0;
+    } else if (SchemaAST.isStringKeyword(propType)) {
+      const currentValue = typeof defaultValue === 'string' ? defaultValue : '';
+      const valueStr = yield* Prompt.text({
+        message: `${info.key}${currentValue ? ` (current: ${currentValue}, press Enter to keep)` : ''}:`,
+      }).pipe(Prompt.run);
+      inputObj[key] = valueStr === '' && defaultValue !== undefined ? defaultValue : valueStr;
+    } else if (Ref.isRefType(propType)) {
+      const isDefaultTemplate =
+        typeof defaultValue === 'string' && defaultValue.startsWith('{{') && defaultValue.endsWith('}}');
+      const useTemplate = yield* Prompt.confirm({
+        message: `Use a template to specify ${info.key}?${isDefaultTemplate ? ' (current: template)' : ''}`,
+        initial: isDefaultTemplate,
+      });
+      if (useTemplate) {
+        const currentValue = typeof defaultValue === 'string' ? defaultValue : '';
+        const templateStr = yield* Prompt.text({
+          message: `${info.key} template${currentValue ? ` (current: ${currentValue}, press Enter to keep)` : ''}:`,
+        }).pipe(Prompt.run);
+        inputObj[key] = templateStr === '' && defaultValue !== undefined ? defaultValue : templateStr;
+      } else {
+        const annotation = Annotation.ReferenceAnnotation.getFromAst(propType).pipe(Option.getOrThrow);
+        const objects = yield* Database.query(Filter.type(DXN.make(annotation.typename))).run;
+        if (objects.length === 0) {
+          inputObj[key] = undefined;
+        } else {
+          const selected = yield* Prompt.select({
+            message: `Select ${info.key}:`,
+            choices: objects.map((obj: Entity.Any) => ({
+              title: Entity.getLabel(obj) ?? obj.id,
+              value: Ref.make(obj),
+              description: Entity.getDescription(obj),
+            })),
+          });
+          inputObj[key] = selected;
+        }
+      }
+    } else {
+      // For other types, prompt as string and let validation handle it
+      const currentValue = defaultValue !== undefined ? String(defaultValue) : '';
+      const valueStr = yield* Prompt.text({
+        message: `${info.key}${currentValue ? ` (current: ${currentValue}, press Enter to keep)` : ''}:`,
+      }).pipe(Prompt.run);
+      inputObj[key] = valueStr === '' && defaultValue !== undefined ? defaultValue : valueStr;
+    }
+  }
+
+  return inputObj;
+});
+
+/**
+ * Selects a function interactively from available functions in the database.
+ * Queries the database for functions and prompts the user to select one.
+ */
+export const selectFunction = Effect.fn(function* () {
+  const allFunctions = yield* Database.query(Filter.type(Operation.PersistentOperation)).run;
+  // Hide internal operations: only operations annotated visible are user-bindable as trigger actions.
+  const functions = allFunctions.filter((fn) => Operation.isVisible(fn));
+
+  if (functions.length === 0) {
+    return yield* Effect.fail(new Error('No functions available'));
+  }
+
+  const selected = yield* Prompt.select({
+    message: 'Select a function:',
+    choices: functions.map((fn: Operation.PersistentOperation) => ({
+      title: fn.name ?? fn.id,
+      value: fn.id,
+      description: fn.description,
+    })),
+  });
+
+  return String(selected);
+});
+
+/**
+ * Selects a trigger interactively from available triggers.
+ * If kind is provided, filters triggers by that kind.
+ * Queries the database for triggers and prompts the user to select one.
+ */
+export const selectTrigger = Effect.fn(function* (kind?: Trigger.Kind) {
+  const triggers = yield* Database.query(
+    Query.select(Filter.type(Trigger.Trigger)).debugLabel('cli.trigger.selectTrigger'),
+  ).run;
+  const filteredTriggers = kind ? triggers.filter((trigger) => trigger.spec?.kind === kind) : triggers;
+
+  if (filteredTriggers.length === 0) {
+    return yield* Effect.fail(new Error(kind ? `No ${kind} triggers available` : 'No triggers available'));
+  }
+
+  const choices = yield* Effect.all(
+    filteredTriggers.map((trigger) =>
+      Effect.gen(function* () {
+        const fn = trigger.runnable ? yield* Database.load(trigger.runnable) : undefined;
+        const functionName =
+          fn && Obj.instanceOf(Operation.PersistentOperation, fn)
+            ? (fn.name ?? Obj.getMeta(fn).key ?? fn.id)
+            : undefined;
+        const title = functionName ?? trigger.id;
+        const description = `${trigger.enabled ? 'enabled' : 'disabled'} - ${trigger.spec?.kind ?? 'unknown'}`;
+
+        return {
+          title,
+          value: trigger.id,
+          description,
+        };
+      }),
+    ),
+  );
+
+  const selected = yield* Prompt.select({
+    message: kind ? `Select a ${kind} trigger:` : 'Select a trigger:',
+    choices,
+  });
+
+  return String(selected);
+});
+
+/**
+ * Selects a feed interactively from available feeds in the database.
+ * Queries schemas with FeedAnnotation, then queries objects of those types,
+ * and returns the chosen Feed object.
+ */
+export const selectFeed = Effect.fn(function* () {
+  // Query schema registry for schemas with FeedAnnotation.
+  const schemas = yield* Database.query(Query.select(Filter.type(Type.Type)).from(Scope.space(), Scope.registry())).run;
+
+  // Filter schemas that have FeedAnnotation.
+  const feedSchemas = schemas.filter((type) => {
+    const schema = Type.getSchema(type);
+    const annotation = FeedAnnotation.get(schema);
+    return Option.isSome(annotation) && annotation.value === true;
+  });
+
+  if (feedSchemas.length === 0) {
+    return yield* Effect.fail(new Error('No schemas with Feed annotation found'));
+  }
+
+  // Collect all Feed objects referenced by host objects.
+  const feedChoices: Array<{ title: string; value: Feed.Feed; description?: string }> = [];
+
+  // Process each feed schema, resolving the Feed object reference.
+  for (const schema of feedSchemas) {
+    yield* Effect.gen(function* () {
+      const objects = yield* Database.query(Filter.type(Type.getURI(schema))).run;
+
+      for (const obj of objects) {
+        // Access the feed property (which is a Ref<Feed>).
+        const feedRef = (obj as any).feed as Ref.Ref<any> | undefined;
+        if (!feedRef) {
+          continue;
+        }
+
+        const feedObj = yield* Effect.promise(() => feedRef.tryLoad());
+        if (!feedObj || !Obj.instanceOf(Feed.Feed, feedObj)) {
+          continue;
+        }
+
+        const label = Obj.getLabel(obj) ?? obj.id;
+        const description = Obj.getTypename(obj);
+
+        feedChoices.push({
+          title: label,
+          value: feedObj,
+          description,
+        });
+      }
+    }).pipe(Effect.catchAll(() => Effect.void));
+  }
+
+  if (feedChoices.length === 0) {
+    return yield* Effect.fail(new Error('No objects with feed properties found'));
+  }
+
+  const selected = yield* Prompt.select({
+    message: 'Select a feed:',
+    choices: feedChoices,
+  });
+
+  return selected as Feed.Feed;
+});
+
+/**
+ * Pretty prints trigger removal result with ANSI colors.
+ */
+export const printTriggerRemoved = (id: string) =>
+  FormBuilder.make({ title: 'Trigger removed' }).pipe(FormBuilder.set('id', id), FormBuilder.build);

package/src/components/CreateRoutinePanel/CreateRoutinePanel.tsx

@@ -0,0 +1,68 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { useCallback, useMemo } from 'react';
+
+import { useCapabilities } from '@dxos/app-framework/ui';
+import { type SpaceCapabilities } from '@dxos/plugin-space';
+import { useTranslation } from '@dxos/react-ui';
+import { SearchList, useSearchListResults } from '@dxos/react-ui-search';
+
+import { meta } from '#meta';
+import { RoutineCapabilities } from '#types';
+
+export type CreateRoutinePanelProps = SpaceCapabilities.CreateObjectCustomPanelProps & {
+  /** Optional override (primarily for stories/tests). Defaults to RoutineCapabilities.Template. */
+  templates?: RoutineCapabilities.Template[];
+};
+
+/**
+ * Create panel for routines: a SearchList picker over contributed templates. Selecting one submits
+ * `{ templateId }`; plugin-routine's CreateObjectEntry.createObject resolves the templateId and runs the
+ * template's `scaffold`.
+ */
+export const CreateRoutinePanel = ({ onCreateObject, templates: templatesProp }: CreateRoutinePanelProps) => {
+  const { t } = useTranslation(meta.profile.key);
+  const capabilityTemplates = useCapabilities(RoutineCapabilities.Template);
+  const templates = templatesProp ?? capabilityTemplates;
+  // The global create dialog has no subject, so subject-required templates (e.g. CRM, which needs a
+  // Mailbox) are excluded; they are offered from the relevant object's Automation companion instead.
+  const sorted = useMemo(
+    () =>
+      [...templates]
+        .filter((template) => template.appliesTo?.(undefined) ?? true)
+        .sort((a, b) => a.label.localeCompare(b.label)),
+    [templates],
+  );
+  const { results, handleSearch } = useSearchListResults({ items: sorted, extract: (template) => template.label });
+
+  const handleSelect = useCallback(
+    (templateId: string) => {
+      void onCreateObject({ templateId });
+    },
+    [onCreateObject],
+  );
+
+  return (
+    <SearchList.Root onSearch={handleSearch}>
+      <SearchList.Input
+        classNames='mb-form-gap'
+        autoFocus
+        data-testid='create-automation-panel.template-input'
+        placeholder={t('create-panel.template.placeholder')}
+      />
+      <SearchList.Viewport>
+        {results.map((template) => (
+          <SearchList.Item
+            key={template.id}
+            value={template.id}
+            label={template.label}
+            icon={template.icon ?? 'ph--lightning--regular'}
+            onSelect={() => handleSelect(template.id)}
+          />
+        ))}
+      </SearchList.Viewport>
+    </SearchList.Root>
+  );
+};

package/src/components/CreateRoutinePanel/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './CreateRoutinePanel';

package/src/components/InstructionsEditor/InstructionsEditor.stories.tsx

@@ -0,0 +1,69 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { Instructions, Skill } from '@dxos/compute';
+import { Filter, Ref } from '@dxos/echo';
+import { type Space, useQuery } from '@dxos/react-client/echo';
+import { useClientStory, withClientProvider } from '@dxos/react-client/testing';
+import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';
+import { Text } from '@dxos/schema';
+
+import { translations } from '#translations';
+
+import { InstructionsEditor } from './InstructionsEditor';
+
+const types = [Instructions.Instructions, Skill.Skill, Text.Text];
+
+const DefaultStory = () => {
+  const { space } = useClientStory();
+  const [instructions] = useQuery(space?.db, Filter.type(Instructions.Instructions));
+  if (!space || !instructions) {
+    return <Loading />;
+  }
+
+  return <InstructionsEditor db={space.db} instructions={instructions} />;
+};
+
+const withSeededSpace = (seed: (space: Space) => void) =>
+  withClientProvider({
+    createIdentity: true,
+    createSpace: true,
+    types,
+    onCreateSpace: async ({ space }) => seed(space),
+  });
+
+const meta = {
+  title: 'plugins/plugin-routine/components/InstructionsEditor',
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: {
+    translations,
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** A routine with no skills or context objects: the form shows empty add affordances. */
+export const Default: Story = {
+  decorators: [
+    withSeededSpace((space) => {
+      space.db.add(Instructions.make({ name: 'Summarize notes' }));
+    }),
+  ],
+};
+
+/** A routine seeded with a context object: the Objects field renders the populated ref slot. */
+export const WithObject: Story = {
+  decorators: [
+    withSeededSpace((space) => {
+      const subject = space.db.add(Text.make({ content: 'Meeting notes' }));
+      space.db.add(Instructions.make({ name: 'Summarize notes', objects: [Ref.make(subject)] }));
+    }),
+  ],
+};

package/src/components/InstructionsEditor/InstructionsEditor.tsx

@@ -0,0 +1,107 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Option from 'effect/Option';
+import React, { useCallback, useMemo } from 'react';
+
+import { Instructions, Skill } from '@dxos/compute';
+import { type Database, Entity, Obj, Type } from '@dxos/echo';
+import { HiddenAnnotation } from '@dxos/echo/Annotation';
+import { Form } from '@dxos/react-ui-form';
+
+const INSTRUCTIONS_SCHEMA = Type.getSchema(Instructions.Instructions);
+
+// Owned-routine action fields surfaced for editing — the prompt text, the agent's `skills`,
+// and the context `objects` bound to its session at run. All live on the Instructions schema,
+// so a single form edits them together.
+const INSTRUCTIONS_FIELDS = new Set(['text', 'skills', 'objects']);
+
+export type InstructionsEditorProps = {
+  db?: Database.Database;
+  instructions: Instructions.Instructions;
+  readonly?: boolean;
+};
+
+/**
+ * Sub-form: edits the owned Instructions in place — its `text` (Markdown), `skills`, and the
+ * context `objects` bound to its session at run, all fields of the Instructions schema. A bare Form.Root +
+ * FieldSet (no Viewport) keeps these fields left-aligned with the sibling general/action forms; the
+ * rendered fields are written back so selections persist to the instructions.
+ */
+export const InstructionsEditor = ({ db: dbProp, instructions, readonly }: InstructionsEditorProps) => {
+  // A draft routine is not yet attached to a database, so fall back to the explicit `db` for ref queries.
+  const db = dbProp ?? Obj.getDatabase(instructions);
+
+  // `objects` is optional; normalize to an array so the ref-array field renders its add affordance.
+  const defaultValues = useMemo<Partial<Instructions.Instructions>>(
+    () => ({ ...Obj.getSnapshot(instructions), objects: instructions.objects ? [...instructions.objects] : [] }),
+    [instructions],
+  );
+
+  const handleValuesChanged = useCallback(
+    (values: Partial<Instructions.Instructions>, { isValid }: { isValid: boolean }) => {
+      // Skip while invalid (e.g. an empty ref slot just added by a skills/objects array field) so a
+      // partial selection isn't persisted; the write lands once the slot is filled.
+      if (!isValid) {
+        return;
+      }
+
+      Obj.update(instructions, (instructions) => {
+        if (values.text) {
+          instructions.text = values.text;
+        }
+        instructions.skills = [...(values.skills ?? [])];
+        instructions.objects = [...(values.objects ?? [])];
+      });
+    },
+    [instructions],
+  );
+
+  return (
+    <Form.Root
+      key={instructions.id}
+      schema={INSTRUCTIONS_SCHEMA}
+      db={db}
+      readonly={readonly}
+      defaultValues={defaultValues}
+      getOptions={getRefOptions}
+      onValuesChanged={handleValuesChanged}
+    >
+      <Form.FieldSet filter={(props) => props.filter((prop) => INSTRUCTIONS_FIELDS.has(prop.name.toString()))} />
+    </Form.Root>
+  );
+};
+
+// System objects (e.g. SpaceProperties) carry `HiddenAnnotation` on their type; they are infrastructure,
+// not user content, so they are excluded from the context picker.
+const isSystemObject = (object: Entity.Any): boolean => {
+  if (!Obj.isObject(object)) {
+    return false;
+  }
+  const typeEntity = Obj.getType(object);
+  if (!typeEntity) {
+    return false;
+  }
+
+  return HiddenAnnotation.get(Type.getSchema(typeEntity)).pipe(Option.getOrElse(() => false));
+};
+
+// Ref-picker options shared by the routine form's skill and object fields: surface a secondary line
+// per candidate — a Skill's registry key, otherwise the object's typename — and sort by label, so the
+// pickers present refs consistently. Falls back to the type placeholder (then URI) for unlabelled objects,
+// matching the default RefField; system objects are excluded.
+const getRefOptions = (
+  results: Entity.Any[],
+  { getTypePlaceholder }: { getTypePlaceholder?: (typename: string) => string } = {},
+): { id: string; label: string; description?: string }[] =>
+  results
+    .filter((entity) => !isSystemObject(entity))
+    .map((entity) => {
+      const id = Entity.getURI(entity, { prefer: 'named' });
+      const typename = Entity.getTypename(entity);
+      const label = Entity.getLabel(entity) ?? (typename ? getTypePlaceholder?.(typename) : undefined) ?? id;
+      const description = Obj.instanceOf(Skill.Skill, entity) ? Obj.getMeta(entity).key : typename;
+      return { id, label, description };
+    })
+    .sort((left, right) => left.label.localeCompare(right.label));

package/src/components/InstructionsEditor/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './InstructionsEditor';