@dxos/plugin-routine 0.0.0

package/src/containers/RoutineTraceCompanion/RoutineTraceCompanion.stories.tsx

@@ -0,0 +1,133 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import React from 'react';
+
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { Trace, Trigger } from '@dxos/compute';
+import { Database, Feed, Filter, Obj, Ref } from '@dxos/echo';
+import { FeedTraceSink } from '@dxos/functions-runtime';
+import { ClientPlugin } from '@dxos/plugin-client/testing';
+import { RoutinePlugin } from '@dxos/plugin-routine/testing';
+import { corePlugins } from '@dxos/plugin-testing';
+import { type Space, useQuery, useSpaces } from '@dxos/react-client/echo';
+import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '#translations';
+import { Routine } from '#types';
+
+import { RoutineTraceCompanion } from './RoutineTraceCompanion';
+
+const types = [Routine.Routine, Trigger.Trigger, Feed.Feed, Trace.Message];
+
+// Fixed base so the seeded runs render deterministically across reloads.
+const BASE = new Date('2026-06-26T09:00:00Z').getTime();
+
+const event = (type: string, offset: number, data: unknown = { key: 'summarize' }): Trace.Event => ({
+  type,
+  timestamp: BASE + offset,
+  data,
+});
+
+/** Build a single-message run whose events match the routine's trigger. */
+const runMessage = (opts: {
+  pid: string;
+  trigger: Ref.Ref<Trigger.Trigger>;
+  events: Trace.Event[];
+  processName?: string;
+}) =>
+  Obj.make(Trace.Message, {
+    meta: { pid: opts.pid, processName: opts.processName, trigger: opts.trigger },
+    isEphemeral: false,
+    events: opts.events,
+  });
+
+/** Seed a routine, its backing trace feed, and a spread of success/failure/pending runs. */
+const seed = (space: Space) =>
+  Effect.gen(function* () {
+    const trigger = Trigger.make({ enabled: true });
+    space.db.add(Routine.make({ name: 'Summarize Notes', trigger }));
+    const feed = space.db.add(
+      Feed.make({ kind: FeedTraceSink.TRACE_FEED_KIND, name: 'Execution Trace', namespace: 'trace' }),
+    );
+    yield* Effect.promise(() => space.db.flush({ indexes: true }));
+
+    const triggerRef = Ref.make(trigger);
+    const messages = [
+      runMessage({
+        pid: 'run-0001',
+        trigger: triggerRef,
+        processName: 'summarize-notes',
+        events: [
+          event(Trace.OperationStart.key, 0),
+          event('tool.call', 800, { tool: 'fetch' }),
+          event(Trace.OperationEnd.key, 2500, { key: 'summarize', outcome: 'success' }),
+        ],
+      }),
+      runMessage({
+        pid: 'run-0002',
+        trigger: triggerRef,
+        events: [
+          event(Trace.OperationStart.key, -60_000),
+          event(Trace.OperationEnd.key, -57_400, { key: 'summarize', outcome: 'failure' }),
+        ],
+      }),
+      runMessage({
+        pid: 'run-0003',
+        trigger: triggerRef,
+        events: [event(Trace.OperationStart.key, -300_000)],
+      }),
+    ];
+
+    yield* Feed.append(feed, messages).pipe(Effect.provide(Database.layer(space.db)));
+    yield* Effect.promise(() => space.db.flush({ indexes: true }));
+  });
+
+const withCompanion = () =>
+  withPluginManager({
+    plugins: [
+      ...corePlugins(),
+      ClientPlugin({
+        types,
+        onClientInitialized: ({ client }) =>
+          Effect.gen(function* () {
+            yield* Effect.promise(() => client.halo.createIdentity());
+            const space = yield* Effect.promise(() => client.spaces.create());
+            yield* Effect.promise(() => space.waitUntilReady());
+            yield* seed(space);
+          }),
+      }),
+      RoutinePlugin(),
+    ],
+  });
+
+const DefaultStory = () => {
+  const spaces = useSpaces();
+  const space = spaces[spaces.length - 1];
+  const [routine] = useQuery(space?.db, Filter.type(Routine.Routine));
+  if (!routine || !space?.db) {
+    return <Loading />;
+  }
+  return <RoutineTraceCompanion role='article' subject={routine} />;
+};
+
+const meta = {
+  title: 'plugins/plugin-routine/containers/RoutineTraceCompanion',
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  decorators: [withCompanion()],
+};

package/src/containers/RoutineTraceCompanion/RoutineTraceCompanion.tsx

@@ -0,0 +1,125 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React from 'react';
+
+import { Obj } from '@dxos/echo';
+import { Icon, Panel, ScrollArea, Toolbar, useTranslation } from '@dxos/react-ui';
+import { Accordion, Empty, Listbox } from '@dxos/react-ui-list';
+import { JsonHighlighter } from '@dxos/react-ui-syntax-highlighter';
+
+import { meta } from '#meta';
+import { Routine } from '#types';
+
+import { type RoutineRun, type RunStatus } from './runs';
+import { useRoutineRuns } from './useRoutineRuns';
+
+const STATUS_ICONS: Record<RunStatus, string> = {
+  success: 'ph--check-circle--regular',
+  failure: 'ph--x-circle--regular',
+  pending: 'ph--clock--regular',
+};
+
+const STATUS_CLASSES: Record<RunStatus, string> = {
+  success: 'text-success-text',
+  failure: 'text-error-text',
+  pending: 'text-description',
+};
+
+export type RoutineTraceCompanionProps = {
+  role?: string;
+  subject: Routine.Routine;
+};
+
+/** Companion panel showing the execution trace (runs) of a Routine. */
+export const RoutineTraceCompanion = ({ role, subject }: RoutineTraceCompanionProps) => {
+  const { t } = useTranslation(meta.profile.key);
+  const db = Obj.getDatabase(subject);
+  const runs = useRoutineRuns(db, subject);
+
+  return (
+    <Panel.Root role={role}>
+      <Panel.Toolbar asChild>
+        <Toolbar.Root />
+      </Panel.Toolbar>
+      <Panel.Content asChild>
+        <ScrollArea.Root orientation='vertical'>
+          <ScrollArea.Viewport>
+            {runs.length === 0 ? (
+              <Empty label={t('history.empty.message')} />
+            ) : (
+              <Accordion.Root<RoutineRun> items={runs} getId={getRunId}>
+                {({ items }) => (
+                  <div className='flex flex-col'>
+                    {items.map((run) => (
+                      <Accordion.Item key={run.pid} item={run} classNames='border-b border-subdued-separator'>
+                        <Accordion.ItemHeader hover>
+                          <Listbox.ItemContent
+                            icon={
+                              <Icon icon={STATUS_ICONS[run.status]} size={5} classNames={STATUS_CLASSES[run.status]} />
+                            }
+                            title={<span className='tabular-nums'>{formatTimestamp(run.startedAt)}</span>}
+                            description={`${t(`history.status.${run.status}.label`)} · ${formatDuration(run.duration)}`}
+                          />
+                        </Accordion.ItemHeader>
+                        {/* Match `ItemContent`'s rail/content grid so the JSON aligns under the title column. */}
+                        <Accordion.ItemBody classNames='grid grid-cols-[var(--dx-rail-item)_1fr] gap-x-2'>
+                          <JsonHighlighter
+                            data={toJsonData(run)}
+                            classNames='col-start-2 [&_pre]:!text-xs [&_code]:!text-xs'
+                          />
+                        </Accordion.ItemBody>
+                      </Accordion.Item>
+                    ))}
+                  </div>
+                )}
+              </Accordion.Root>
+            )}
+          </ScrollArea.Viewport>
+        </ScrollArea.Root>
+      </Panel.Content>
+    </Panel.Root>
+  );
+};
+
+const formatDuration = (ms: number): string => {
+  if (ms < 1000) {
+    return `${ms}ms`;
+  }
+  if (ms < 60_000) {
+    return `${(ms / 1000).toFixed(1)}s`;
+  }
+  const totalSeconds = Math.round(ms / 1000);
+  const mins = Math.floor(totalSeconds / 60);
+  const secs = totalSeconds % 60;
+  return `${mins}m ${secs}s`;
+};
+
+const formatTimestamp = (ts: number): string =>
+  new Date(ts).toLocaleString(undefined, {
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hour12: false,
+  });
+
+const toJsonData = (run: RoutineRun) => ({
+  pid: run.pid,
+  startedAt: new Date(run.startedAt).toISOString(),
+  duration: run.duration,
+  status: run.status,
+  ...(run.conversation && { conversation: run.conversation.uri }),
+  events: run.events.map((evt) => ({
+    type: evt.type,
+    timestamp: new Date(evt.timestamp).toISOString(),
+    ...(evt.pid && { pid: evt.pid }),
+    ...(evt.processName && { processName: evt.processName }),
+    data: evt.data,
+  })),
+});
+
+const getRunId = (run: RoutineRun) => run.pid;

package/src/containers/RoutineTraceCompanion/index.ts

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

package/src/containers/RoutineTraceCompanion/runs.test.ts

@@ -0,0 +1,140 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { Trace } from '@dxos/compute';
+import { Obj, Ref } from '@dxos/echo';
+import { EID, type EntityId } from '@dxos/keys';
+
+import { groupIntoRuns } from './runs';
+
+const TRIGGER_ID = 'aaaaaaaa-0000-0000-0000-000000000001' as EntityId;
+const OTHER_TRIGGER_ID = 'bbbbbbbb-0000-0000-0000-000000000002' as EntityId;
+
+describe('groupIntoRuns', () => {
+  test('returns empty for no messages', ({ expect }) => {
+    const runs = groupIntoRuns([], new Set([TRIGGER_ID]));
+    expect(runs).toHaveLength(0);
+  });
+
+  test('returns empty when no messages match trigger ids', ({ expect }) => {
+    const msg = makeMessage({ pid: 'p1', triggerEntityId: OTHER_TRIGGER_ID });
+    const runs = groupIntoRuns([msg], new Set([TRIGGER_ID]));
+    expect(runs).toHaveLength(0);
+  });
+
+  test('groups a single successful run', ({ expect }) => {
+    const start = makeMessage({
+      pid: 'p1',
+      triggerEntityId: TRIGGER_ID,
+      eventType: Trace.OperationStart.key,
+      timestamp: 1000,
+    });
+    const end = makeMessage({
+      pid: 'p1',
+      triggerEntityId: TRIGGER_ID,
+      eventType: Trace.OperationEnd.key,
+      eventOutcome: 'success',
+      timestamp: 3000,
+    });
+    const runs = groupIntoRuns([start, end], new Set([TRIGGER_ID]));
+    expect(runs).toHaveLength(1);
+    expect(runs[0].pid).toBe('p1');
+    expect(runs[0].status).toBe('success');
+    expect(runs[0].startedAt).toBe(1000);
+    expect(runs[0].duration).toBe(2000);
+  });
+
+  test('marks run as failed when any OperationEnd is failure', ({ expect }) => {
+    const start = makeMessage({
+      pid: 'p1',
+      triggerEntityId: TRIGGER_ID,
+      eventType: Trace.OperationStart.key,
+      timestamp: 1000,
+    });
+    const end = makeMessage({
+      pid: 'p1',
+      triggerEntityId: TRIGGER_ID,
+      eventType: Trace.OperationEnd.key,
+      eventOutcome: 'failure',
+      timestamp: 2000,
+    });
+    const runs = groupIntoRuns([start, end], new Set([TRIGGER_ID]));
+    expect(runs[0].status).toBe('failure');
+  });
+
+  test('marks run as pending when no OperationEnd event present', ({ expect }) => {
+    const start = makeMessage({ pid: 'p1', triggerEntityId: TRIGGER_ID, timestamp: 1000 });
+    const runs = groupIntoRuns([start], new Set([TRIGGER_ID]));
+    expect(runs[0].status).toBe('pending');
+  });
+
+  test('sorts runs newest first', ({ expect }) => {
+    const older = makeMessage({ pid: 'p1', triggerEntityId: TRIGGER_ID, timestamp: 1000 });
+    const newer = makeMessage({ pid: 'p2', triggerEntityId: TRIGGER_ID, timestamp: 5000 });
+    const runs = groupIntoRuns([older, newer], new Set([TRIGGER_ID]));
+    expect(runs[0].pid).toBe('p2');
+    expect(runs[1].pid).toBe('p1');
+  });
+
+  test('child process messages roll up to root run', ({ expect }) => {
+    const parent = makeMessage({ pid: 'p1', triggerEntityId: TRIGGER_ID, timestamp: 1000 });
+    const child = makeMessage({ pid: 'p2', parentPid: 'p1', triggerEntityId: TRIGGER_ID, timestamp: 2000 });
+    const runs = groupIntoRuns([parent, child], new Set([TRIGGER_ID]));
+    // Both messages belong to the same root run 'p1'.
+    expect(runs).toHaveLength(1);
+    expect(runs[0].pid).toBe('p1');
+    expect(runs[0].duration).toBe(1000);
+  });
+
+  test('deep parent chain (>20 levels) resolves to root run', ({ expect }) => {
+    const depth = 25;
+    const messages: Trace.Message[] = [];
+    for (let i = 1; i <= depth; i++) {
+      messages.push(
+        makeMessage({
+          pid: `p${i}`,
+          parentPid: i > 1 ? `p${i - 1}` : undefined,
+          triggerEntityId: TRIGGER_ID,
+          timestamp: i * 1000,
+        }),
+      );
+    }
+    const runs = groupIntoRuns(messages, new Set([TRIGGER_ID]));
+    expect(runs).toHaveLength(1);
+    expect(runs[0].pid).toBe('p1');
+  });
+});
+
+// Minimal Ref whose `.uri` is a valid EID.
+// EntityId is a branded string — the cast on the caller's side is intentional for test fixtures.
+function makeRef(entityId: EntityId): Ref.Ref<never> {
+  return Ref.fromURI(EID.make({ entityId })) as Ref.Ref<never>;
+}
+
+// Construct a bare-minimum Trace.Message for testing (no ECHO DB required).
+function makeMessage(opts: {
+  pid: string;
+  parentPid?: string;
+  triggerEntityId?: EntityId;
+  eventType?: string;
+  eventOutcome?: string;
+  timestamp?: number;
+}): Trace.Message {
+  const event = {
+    type: opts.eventType ?? Trace.OperationStart.key,
+    timestamp: opts.timestamp ?? Date.now(),
+    data: opts.eventOutcome ? { key: 'test', outcome: opts.eventOutcome } : { key: 'test' },
+  } as Trace.Event;
+  return Obj.make(Trace.Message, {
+    meta: {
+      pid: opts.pid,
+      parentPid: opts.parentPid,
+      trigger: opts.triggerEntityId ? makeRef(opts.triggerEntityId) : undefined,
+    },
+    isEphemeral: false,
+    events: [event],
+  });
+}

package/src/containers/RoutineTraceCompanion/runs.ts

@@ -0,0 +1,135 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Trace } from '@dxos/compute';
+import { type Obj, type Ref } from '@dxos/echo';
+import { EID } from '@dxos/keys';
+
+export type RunStatus = 'success' | 'failure' | 'pending';
+
+export type RunEvent = {
+  type: string;
+  timestamp: number;
+  data: unknown;
+  /** Process id that emitted this event; present when a run spawns child processes. */
+  pid?: string;
+  /** Human-readable process name, if provided by the runtime. */
+  processName?: string;
+};
+
+export type RoutineRun = {
+  /** Root process id. */
+  pid: string;
+  startedAt: number;
+  duration: number;
+  status: RunStatus;
+  /** All trace events for this run, sorted chronologically. */
+  events: RunEvent[];
+  /** Ref to the conversation (chat feed) created for this run, if any. */
+  conversation?: Ref.Ref<Obj.Unknown>;
+};
+
+/**
+ * Groups trace messages into per-run summaries.
+ *
+ * Only root processes (those whose `meta.parentPid` is absent) are considered
+ * run entry points. Child processes contribute their events to the run duration
+ * and outcome but do not create separate run entries.
+ *
+ * The triggerIds set identifies which messages belong to this routine.
+ */
+export const groupIntoRuns = (
+  messages: readonly Trace.Message[],
+  triggerEntityIds: ReadonlySet<string>,
+): RoutineRun[] => {
+  // Filter to messages whose trigger ref matches one of the routine's triggers.
+  const relevant = messages.filter((msg) => {
+    if (!msg.meta.trigger) {
+      return false;
+    }
+    const eid = EID.getEntityId(EID.parse(msg.meta.trigger.uri));
+    return eid !== undefined && triggerEntityIds.has(eid);
+  });
+
+  if (relevant.length === 0) {
+    return [];
+  }
+
+  // Collect all pids and their parent relationships.
+  const pidToParent = new Map<string, string>();
+  for (const msg of relevant) {
+    if (msg.meta.pid) {
+      if (msg.meta.parentPid) {
+        pidToParent.set(msg.meta.pid, msg.meta.parentPid);
+      }
+    }
+  }
+
+  // Find the root pid for a given pid (walk up the parent chain).
+  const getRootPid = (pid: string): string => {
+    let current = pid;
+    const visited = new Set<string>();
+    while (!visited.has(current)) {
+      visited.add(current);
+      const parent = pidToParent.get(current);
+      if (!parent) {
+        return current;
+      }
+      current = parent;
+    }
+    // Cycle detected; return a stable fallback key.
+    return current;
+  };
+
+  // Group messages by root pid.
+  const byRoot = new Map<string, Trace.Message[]>();
+  for (const msg of relevant) {
+    if (!msg.meta.pid) {
+      continue;
+    }
+    const rootPid = getRootPid(msg.meta.pid);
+    const group = byRoot.get(rootPid) ?? [];
+    group.push(msg);
+    byRoot.set(rootPid, group);
+  }
+
+  const runs: RoutineRun[] = [];
+  for (const [pid, msgs] of byRoot) {
+    const allEvents = msgs.flatMap((msg) => msg.events.map((evt) => ({ ...evt, meta: msg.meta })));
+    allEvents.sort((left, right) => left.timestamp - right.timestamp);
+
+    const startedAt = allEvents[0]?.timestamp ?? 0;
+    const lastTimestamp = allEvents.at(-1)?.timestamp ?? startedAt;
+    const duration = lastTimestamp - startedAt;
+
+    // Determine status from OperationEnd events — failure beats success.
+    let status: RunStatus = 'pending';
+    for (const evt of allEvents) {
+      if (Trace.isOfType(Trace.OperationEnd, evt)) {
+        if (evt.data.outcome === 'failure') {
+          status = 'failure';
+          break;
+        }
+        status = 'success';
+      }
+    }
+
+    // Grab the conversation ref from any message in this run that has one.
+    const conversation = msgs.find((msg) => msg.meta.conversation)?.meta.conversation;
+
+    const events: RunEvent[] = allEvents.map((evt) => ({
+      type: evt.type,
+      timestamp: evt.timestamp,
+      data: evt.data,
+      ...(evt.meta.pid && { pid: evt.meta.pid }),
+      ...(evt.meta.processName && { processName: evt.meta.processName }),
+    }));
+
+    runs.push({ pid, startedAt, duration, status, events, conversation });
+  }
+
+  // Newest first.
+  runs.sort((left, right) => right.startedAt - left.startedAt);
+  return runs;
+};

package/src/containers/RoutineTraceCompanion/useRoutineRuns.ts

@@ -0,0 +1,50 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useMemo } from 'react';
+
+import { Trace } from '@dxos/compute';
+import { type Database, Filter, Query } from '@dxos/echo';
+import { FeedTraceSink } from '@dxos/functions-runtime';
+import { EID } from '@dxos/keys';
+import { useQuery } from '@dxos/react-client/echo';
+
+import { type Routine } from '#types';
+
+import { type RoutineRun, groupIntoRuns } from './runs';
+
+/**
+ * Returns the execution runs for a routine.
+ *
+ * Reads from the per-space trace feed and filters to messages whose
+ * `meta.trigger` ref matches one of the routine's triggers.
+ */
+export const useRoutineRuns = (db: Database.Database | undefined, routine: Routine.Routine): RoutineRun[] => {
+  const [traceFeed] = useQuery(db, FeedTraceSink.query);
+
+  const messages = useQuery(
+    db,
+    traceFeed ? Query.select(Filter.type(Trace.Message)).from(traceFeed) : Query.select(Filter.nothing()),
+  );
+
+  const triggerEntityIds = useMemo<ReadonlySet<string>>(() => {
+    const ids = new Set<string>();
+    for (const triggerRef of routine.triggers) {
+      if (!triggerRef) {
+        continue;
+      }
+      const uri = triggerRef.uri;
+      if (!uri) {
+        continue;
+      }
+      const eid = EID.getEntityId(EID.parse(uri));
+      if (eid) {
+        ids.add(eid);
+      }
+    }
+    return ids;
+  }, [routine.triggers.map((triggerRef) => triggerRef?.uri ?? '').join('|')]);
+
+  return useMemo(() => groupIntoRuns(messages, triggerEntityIds), [messages, triggerEntityIds]);
+};

package/src/containers/SkillArticle/SkillArticle.tsx

@@ -0,0 +1,29 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { type Skill } from '@dxos/compute';
+import { Panel, Toolbar } from '@dxos/react-ui';
+import { useAttention } from '@dxos/react-ui-attention';
+
+import { TemplateEditor } from '#components';
+
+export type SkillArticleProps = AppSurface.ObjectArticleProps<Skill.Skill>;
+
+export const SkillArticle = ({ role, attendableId, subject }: SkillArticleProps) => {
+  const { hasAttention } = useAttention(attendableId);
+
+  return (
+    <Panel.Root role={role} classNames='dx-document'>
+      <Panel.Toolbar asChild>
+        <Toolbar.Root disabled={!hasAttention} />
+      </Panel.Toolbar>
+      <Panel.Content asChild>
+        <TemplateEditor id={subject.id} source={subject.instructions.source} />
+      </Panel.Content>
+    </Panel.Root>
+  );
+};

package/src/containers/SkillArticle/index.ts

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

package/src/containers/index.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type ComponentType, lazy } from 'react';
+
+export const RoutineArticle: ComponentType<any> = lazy(() => import('./RoutineArticle'));
+export const RoutineTraceCompanion: ComponentType<any> = lazy(() => import('./RoutineTraceCompanion'));
+export const RoutineSettings: ComponentType<any> = lazy(() => import('./RoutineSettings'));
+export const RoutineCompanion: ComponentType<any> = lazy(() => import('./RoutineCompanion'));
+export const SkillArticle: ComponentType<any> = lazy(() => import('./SkillArticle'));

package/src/hooks/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// TODO(wittjosiah): Factor out.
+export * from './useTriggerRuntimeControls';