@dxos/react-ui-trace 0.11.1

package/src/hooks/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './useExecutionGraph.ts';
+export * from './useSessionTimeline.ts';
+export * from './useTraceMessages.ts';

package/src/hooks/useExecutionGraph.ts

@@ -0,0 +1,107 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useAtomValue } from '@effect/atom-react/Hooks';
+import * as Duration from 'effect/Duration';
+import { pipe } from 'effect/Function';
+import * as Atom from 'effect/unstable/reactivity/Atom';
+import { useEffect, useMemo, useState } from 'react';
+
+import * as Process from '@dxos/compute/Process';
+import { type Space } from '@dxos/react-client/echo';
+
+import { filterTraceMessages } from '../components/TracePanel/trace-filter.ts';
+import { type ExecutionGraph, buildExecutionGraph } from '../execution-graph/index.ts';
+
+import { getTraceMessagesAtom } from './useTraceMessages.ts';
+
+// Stable refs.
+const atomEmpty = Atom.make(() => [] as const);
+const NO_PIDS: readonly string[] = [];
+
+// How often the graph re-checks for spans that timed out with no closing event.
+// Coarse-grained on purpose: `spanTimeoutMs` operates on a 20-minute scale, so there is no
+// benefit to re-deriving the graph more often than this just to catch the timeout crossing.
+const SPAN_TIMEOUT_CHECK_INTERVAL_MS = 60_000;
+
+export type UseExecutionGraphOptions = {
+  collapseCompletedSpans?: boolean;
+  eventLimit?: number;
+  /** Pids to narrow the graph to (with their descendants); empty shows everything. */
+  selectedPids?: readonly string[];
+};
+
+/**
+ * The commit graph of a space's trace, rebuilt as messages land and as the process tree changes.
+ * `processesAtom` is the host's live process tree (a running agent draws a spinner commit); without
+ * it the graph is the durable trace alone.
+ */
+export const useExecutionGraph = (
+  space: Space,
+  processesAtom: Atom.Atom<readonly Process.Info[]> | undefined,
+  { collapseCompletedSpans, eventLimit, selectedPids = NO_PIDS }: UseExecutionGraphOptions = {},
+): ExecutionGraph => {
+  // Ticks periodically so spans that are still open purely because no new trace event has
+  // arrived (e.g. the runtime crashed before writing its `operationEnd`) eventually get
+  // force-closed by `buildExecutionGraph`'s `spanTimeoutMs` check, instead of staying stuck
+  // until unrelated trace activity happens to trigger a recompute.
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    const id = setInterval(() => setNow(Date.now()), SPAN_TIMEOUT_CHECK_INTERVAL_MS);
+    return () => clearInterval(id);
+  }, []);
+
+  const atom = useMemo(
+    () =>
+      getExecutionGraph(space, processesAtom ?? atomEmpty, { collapseCompletedSpans, eventLimit, selectedPids, now }),
+    [space, processesAtom, collapseCompletedSpans, eventLimit, selectedPids, now],
+  );
+
+  return useAtomValue(atom);
+};
+
+/** Identity for the graph: only a process appearing, disappearing or changing state redraws it. */
+const sameProcesses = (left: readonly Process.Info[], right: readonly Process.Info[]): boolean =>
+  left.length === right.length &&
+  left.every((process, index) => process.pid === right[index].pid && process.state === right[index].state);
+
+const getExecutionGraph = (
+  space: Space,
+  processesAtom: Atom.Atom<readonly Process.Info[]>,
+  {
+    collapseCompletedSpans = true,
+    eventLimit = 100,
+    selectedPids = NO_PIDS,
+    now,
+  }: UseExecutionGraphOptions & { now: number },
+): Atom.Atom<ExecutionGraph> => {
+  const traceMessages = getTraceMessagesAtom(space).pipe(
+    Atom.map((messages) => filterTraceMessages(messages, selectedPids)),
+  );
+
+  const activeProcesses = pipe(
+    processesAtom,
+    Atom.debounce(Duration.millis(500)),
+    Atom.map((processes) =>
+      processes.filter(
+        (process) =>
+          (process.state === Process.State.RUNNING || process.state === Process.State.HYBERNATING) &&
+          (selectedPids.length === 0 || selectedPids.includes(process.pid)),
+      ),
+    ),
+    // The monitor rebuilds the process list on every poll, so without a structural comparison the
+    // graph would be rebuilt on each tick even when nothing moved.
+    Atom.withEquality(sameProcesses),
+  );
+
+  return Atom.make((get) =>
+    buildExecutionGraph({
+      traceMessages: get(traceMessages),
+      activeProcesses: get(activeProcesses),
+      collapseCompletedSpans,
+      eventLimit,
+      now,
+    }),
+  );
+};

package/src/hooks/useSessionTimeline.ts

@@ -0,0 +1,53 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Duration from 'effect/Duration';
+import { useEffect, useMemo, useState } from 'react';
+
+import type * as Process from '@dxos/compute/Process';
+import { type Space } from '@dxos/react-client/echo';
+import { type Task } from '@dxos/types';
+
+import { type Session, type SessionTimeline, buildSessionTimeline } from '../session-timeline/index.ts';
+
+import { useTraceMessages } from './useTraceMessages.ts';
+
+/** How often `now` advances while a session is open, so a running lane's range keeps growing. */
+const TICK_MS = 5_000;
+
+// The trace feed emits continuously while anything runs, and every emission rebuilds the whole
+// timeline from the full message history — so the rebuild rate is capped rather than the feed's.
+const TRACE_DEBOUNCE = Duration.millis(500);
+
+const NO_PROCESSES: readonly Process.Info[] = [];
+
+export type UseSessionTimelineOptions = {
+  /** The sessions shown; each contributes a session lane and its checklist's task lanes. */
+  sessions: readonly Session[];
+  tasks?: readonly Task.Task[];
+  /** The live process tree, from whichever monitor the host has; without it a session's liveness is read from the trace alone. */
+  processes?: readonly Process.Info[];
+};
+
+/**
+ * The live gantt-shaped view of the given sessions: rebuilt as trace events land on the space's
+ * trace feed and as the process tree changes, and ticked so open lanes keep extending.
+ */
+export const useSessionTimeline = (
+  space: Space | undefined,
+  { sessions, tasks, processes = NO_PROCESSES }: UseSessionTimelineOptions,
+): SessionTimeline => {
+  const traceMessages = useTraceMessages(space, { debounce: TRACE_DEBOUNCE });
+
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    const interval = setInterval(() => setNow(Date.now()), TICK_MS);
+    return () => clearInterval(interval);
+  }, []);
+
+  return useMemo(
+    () => buildSessionTimeline({ traceMessages, processes, sessions, tasks, now }),
+    [traceMessages, processes, sessions, tasks, now],
+  );
+};

package/src/hooks/useTraceMessages.ts

@@ -0,0 +1,58 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useAtomValue } from '@effect/atom-react/Hooks';
+import * as Duration from 'effect/Duration';
+import { pipe } from 'effect/Function';
+import * as Atom from 'effect/unstable/reactivity/Atom';
+import { useMemo } from 'react';
+
+import { FeedTraceSink } from '@dxos/compute-runtime';
+import * as Trace from '@dxos/compute/Trace';
+import { Filter, Query } from '@dxos/echo';
+import { type Space } from '@dxos/react-client/echo';
+
+const atomEmpty = Atom.make(() => [] as const);
+
+/**
+ * Atom of raw trace messages for a space — the input to `buildExecutionGraph`.
+ */
+export const getTraceMessagesAtom = (space: Space): Atom.Atom<readonly Trace.Message[]> =>
+  pipe(
+    space.db.query(FeedTraceSink.query).atom,
+    Atom.map(
+      (feeds) =>
+        // Query across ALL trace feeds: writers race on feed creation (the edge's indexer-backed
+        // lookup can miss a not-yet-indexed feed and create a duplicate), so a space may hold
+        // several trace feeds — reading only one would silently drop the others' events.
+        space.db.query(
+          feeds.length > 0
+            ? Query.type(Trace.Message).from([...feeds])
+            : (Query.select(Filter.nothing()) as Query.Query<never>),
+        ).atom,
+    ),
+    (atom) => Atom.make((get) => get(get(atom))),
+  );
+
+export type UseTraceMessagesOptions = {
+  /** Caps the re-render rate; the feed emits per message, which is far faster than a reader can read. */
+  debounce?: Duration.Duration;
+};
+
+/**
+ * Subscribes to the space invocation trace feed.
+ */
+export const useTraceMessages = (
+  space?: Space,
+  { debounce }: UseTraceMessagesOptions = {},
+): readonly Trace.Message[] => {
+  const atom = useMemo(() => {
+    if (!space) {
+      return atomEmpty;
+    }
+    const traces = getTraceMessagesAtom(space);
+    return debounce ? traces.pipe(Atom.debounce(debounce)) : traces;
+  }, [space, debounce]);
+  return useAtomValue(atom);
+};

package/src/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './components/index.ts';
+export * from './execution-graph/index.ts';
+export * from './hooks/index.ts';
+export * from './session-timeline/index.ts';

package/src/session-timeline/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './session-timeline.ts';
+export * from './types.ts';