@dxos/react-ui-trace 0.11.1

package/src/execution-graph/execution-graph.ts

@@ -0,0 +1,1076 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Array from 'effect/Array';
+import { pipe } from 'effect/Function';
+import * as Option from 'effect/Option';
+import * as Pipeable from 'effect/Pipeable';
+import * as Schema from 'effect/Schema';
+import * as Struct from 'effect/Struct';
+
+import { RUN_AGAIN_ERROR_CODE, RUN_AGAIN_MESSAGE } from '@dxos/compute';
+import * as Process from '@dxos/compute/Process';
+import * as Trace from '@dxos/compute/Trace';
+import { Annotation } from '@dxos/echo';
+import { EID } from '@dxos/keys';
+import { LogLevel, log } from '@dxos/log';
+import { type Commit } from '../components/Timeline/index.ts';
+import { type ContentBlock } from '@dxos/types';
+
+import { ROOT_SPAN_ID, type Span, buildSpanTree, isSpanBeginEvent, isSpanEndEvent, walkSpanTree } from './span-tree.ts';
+
+/**
+ * Branch name for top-level operation invocations.
+ */
+const MAIN_BRANCH = 'main';
+
+/** Timeline tag that applies a shimmer message effect. */
+const SHIMMER_EFFECT_TAG = 'effect:shimmer';
+
+const ICONS = {
+  agentRequestBegin: {
+    icon: 'ph--atom--regular',
+    level: LogLevel.VERBOSE,
+  },
+  agentRequestEndSuccess: {
+    icon: 'ph--atom--regular',
+    level: LogLevel.INFO,
+  },
+  agentRequestEndError: {
+    icon: 'ph--atom--regular',
+    level: LogLevel.ERROR,
+  },
+  agentRequestEndInterrupted: {
+    icon: 'ph--atom--regular',
+    level: LogLevel.WARN,
+  },
+  userMessage: {
+    icon: 'ph--user--regular',
+    level: LogLevel.VERBOSE,
+  },
+  statusMessage: {
+    icon: 'ph--info--regular',
+    level: LogLevel.VERBOSE,
+  },
+  operationStart: {
+    icon: 'ph--function--regular',
+    level: LogLevel.VERBOSE,
+  },
+  operationEndSuccess: {
+    icon: 'ph--function--regular',
+    level: LogLevel.INFO,
+  },
+  operationEndError: {
+    icon: 'ph--function--regular',
+    level: LogLevel.ERROR,
+  },
+  operationEndIncomplete: {
+    icon: 'ph--arrows-clockwise--regular',
+    level: LogLevel.WARN,
+  },
+  toolCall: {
+    icon: 'ph--wrench--regular',
+    level: LogLevel.VERBOSE,
+  },
+  toolResultSuccess: {
+    icon: 'ph--wrench--regular',
+    level: LogLevel.INFO,
+  },
+  toolResultError: {
+    icon: 'ph--wrench--regular',
+    level: LogLevel.ERROR,
+  },
+  agentRequestRunning: {
+    icon: 'ph--spinner-gap--regular',
+    level: LogLevel.VERBOSE,
+  },
+  processRunning: {
+    icon: 'ph--spinner-gap--regular',
+    level: LogLevel.VERBOSE,
+  },
+} as const;
+
+export interface BuildExecutionGraphParams {
+  traceMessages: readonly Trace.Message[];
+  activeProcesses?: readonly Process.Info[];
+  collapseCompletedSpans?: boolean;
+  eventLimit?: number;
+  /**
+   * Duration a span may sit open with no new events before it's force-closed with a synthetic
+   * end event. Only takes effect when `now` is also provided. Defaults to
+   * `DEFAULT_SPAN_TIMEOUT_MS`.
+   */
+  spanTimeoutMs?: number;
+  /**
+   * Reference time used to detect abandoned spans. Force-closing is skipped entirely when this
+   * is omitted.
+   */
+  now?: number;
+}
+
+/**
+ * Builds a Timeline-compatible execution graph from trace messages and active processes.
+ *
+ * The conversion runs in two stages:
+ *   1. `buildSpanTree` converts the flat list of trace messages into a hierarchical
+ *      tree of spans grouped by process id (pid). See `./span-tree.ts`.
+ *   2. `spanTreeToCommits` walks the tree and emits one commit per event, using the
+ *      tree structure to decide which branch each commit belongs to and how to wire parents.
+ *
+ * Pure function — no signals or atoms.
+ */
+export type ExecutionGraph = {
+  branches: string[];
+  commits: Commit[];
+  spanTree: Span;
+  /** Commit id -> trace event. */
+  details: ExecutionGraphDetailsMap;
+};
+
+export type ExecutionGraphDetailsMap = Record<string, Trace.FlatEvent | undefined>;
+
+export const buildExecutionGraph = ({
+  traceMessages,
+  activeProcesses = [],
+  collapseCompletedSpans = false,
+  eventLimit = 500,
+  spanTimeoutMs,
+  now,
+}: BuildExecutionGraphParams): ExecutionGraph => {
+  const spanTree = buildSpanTree(traceMessages, { eventLimit, spanTimeoutMs, now });
+  const toolCallContext = buildToolCallContext(traceMessages);
+  const built = spanTreeToCommits(spanTree, activeProcesses, toolCallContext, collapseCompletedSpans);
+  log('trace execution graph', {
+    traceMessages: traceMessages.length,
+    commits: built.commits.length,
+    branches: built.branches.length,
+    activeProcesses: activeProcesses.length,
+  });
+  return { ...built, spanTree };
+};
+
+/**
+ * Lookup tables that pair `toolCall` blocks with their matching `toolResult` blocks so the
+ * renderer can collapse the two events into a single commit (mirroring how begin/end events of
+ * an empty operation span collapse). Indexed by the shared `toolCallId`.
+ */
+interface ToolCallContext {
+  callById: Map<string, ContentBlock.ToolCall>;
+  resultByCallId: Map<string, ContentBlock.ToolResult>;
+}
+
+const buildToolCallContext = (messages: readonly Trace.Message[]): ToolCallContext => {
+  const callById = new Map<string, ContentBlock.ToolCall>();
+  const resultByCallId = new Map<string, ContentBlock.ToolResult>();
+  for (const message of messages) {
+    for (const event of message.events) {
+      if (event.type !== Trace.CompleteBlock.key) {
+        continue;
+      }
+      const data = event.data as { block?: ContentBlock.Any } | undefined;
+      const block = data?.block;
+      if (!block) {
+        continue;
+      }
+      if (block._tag === 'toolCall') {
+        callById.set(block.toolCallId, block);
+      } else if (block._tag === 'toolResult') {
+        resultByCallId.set(block.toolCallId, block);
+      }
+    }
+  }
+  return { callById, resultByCallId };
+};
+
+/**
+ * Visual representation of a single trace event — icon, log level, message string.
+ * `undefined` indicates that the event should not produce a commit.
+ */
+interface EventPresentation {
+  icon: string;
+  level: LogLevel;
+  message: string;
+  idSuffix?: string;
+}
+
+type AgentRequestEndData = Schema.Schema.Type<typeof Trace.AgentRequestEnd.schema>;
+
+/**
+ * Parses `Trace.AgentRequestEnd` payload, accepting legacy traces that omitted `status`.
+ */
+const parseAgentRequestEnd = (data: unknown): AgentRequestEndData | undefined => {
+  if (Schema.is(Trace.AgentRequestEnd.schema)(data)) {
+    return data;
+  }
+  // Traces emitted before `status` was added wrote an empty object.
+  if (data != null && typeof data === 'object' && Object.keys(data).length === 0) {
+    return { status: 'success' };
+  }
+  log('invalid trace event', { type: Trace.AgentRequestEnd.key });
+  return undefined;
+};
+
+const presentAgentRequestEnd = (data: AgentRequestEndData): EventPresentation => {
+  switch (data.status) {
+    case 'error':
+      return {
+        icon: ICONS.agentRequestEndError.icon,
+        level: ICONS.agentRequestEndError.level,
+        message: data.error ? trimText(`Agent request failed: ${data.error}`) : 'Agent request failed',
+      };
+    case 'interrupted':
+      return {
+        icon: ICONS.agentRequestEndInterrupted.icon,
+        level: ICONS.agentRequestEndInterrupted.level,
+        message: 'Agent request interrupted',
+      };
+    default:
+      return {
+        icon: ICONS.agentRequestEndSuccess.icon,
+        level: ICONS.agentRequestEndSuccess.level,
+        message: 'Agent completed request',
+      };
+  }
+};
+
+const presentEvent = (event: Trace.FlatEvent, toolCallContext: ToolCallContext): EventPresentation | undefined => {
+  if (Trace.isOfType(Trace.AgentRequestBegin, event)) {
+    if (!Schema.is(Trace.AgentRequestBegin.schema)(event.data)) {
+      log('invalid trace event', { type: event.type });
+      return undefined;
+    }
+    return {
+      icon: ICONS.agentRequestBegin.icon,
+      level: ICONS.agentRequestBegin.level,
+      message: 'Agent processing request...',
+    };
+  }
+  if (Trace.isOfType(Trace.AgentRequestEnd, event)) {
+    const endData = parseAgentRequestEnd(event.data);
+    if (!endData) {
+      return undefined;
+    }
+    return presentAgentRequestEnd(endData);
+  }
+  if (Trace.isOfType(Trace.CompleteBlock, event)) {
+    if (!Schema.is(Trace.CompleteBlock.schema)(event.data)) {
+      log('invalid trace event', { type: event.type });
+      return undefined;
+    }
+    switch (event.data.block._tag) {
+      case 'text':
+        return event.data.role === 'user'
+          ? {
+              icon: ICONS.userMessage.icon,
+              level: ICONS.userMessage.level,
+              message: trimText(event.data.block.text),
+            }
+          : undefined;
+      case 'status':
+        return {
+          icon: ICONS.statusMessage.icon,
+          level: ICONS.statusMessage.level,
+          message: trimText(event.data.block.statusText),
+        };
+      case 'toolCall': {
+        // Operation-backed tool calls already have a dedicated routine span (Trace.OperationStart /
+        // Trace.OperationEnd) that produces its own commits — skip the duplicate toolCall commit
+        // to avoid double-rendering.
+        if (event.data.block.operationKey) {
+          return undefined;
+        }
+        // Collapse the toolCall/toolResult pair: when the matching toolResult has arrived, the
+        // result event is the visible commit and carries the success/error state. The toolCall
+        // itself only renders while still pending (i.e. no result yet) — same intent as an
+        // operation span that collapses to a single end commit once both boundaries are present.
+        if (toolCallContext.resultByCallId.has(event.data.block.toolCallId)) {
+          return undefined;
+        }
+        return {
+          icon: ICONS.toolCall.icon,
+          level: ICONS.toolCall.level,
+          message: event.data.block.name,
+          idSuffix: `toolCall:${event.data.block.toolCallId}`,
+        };
+      }
+      case 'toolResult': {
+        // Suppress results for operation-backed calls — those are covered by the routine span.
+        const call = toolCallContext.callById.get(event.data.block.toolCallId);
+        if (call?.operationKey) {
+          return undefined;
+        }
+        const success = event.data.block.error === undefined;
+        const name = call?.name ?? event.data.block.name;
+        return {
+          icon: success ? ICONS.toolResultSuccess.icon : ICONS.toolResultError.icon,
+          level: success ? ICONS.toolResultSuccess.level : ICONS.toolResultError.level,
+          message: `${name}${!success ? ' - Error' : ''}`,
+          idSuffix: `toolResult:${event.data.block.toolCallId}`,
+        };
+      }
+      default:
+        return undefined;
+    }
+  }
+  if (Trace.isOfType(Trace.OperationStart, event)) {
+    if (!Schema.is(Trace.OperationStart.schema)(event.data)) {
+      log('invalid trace event', { type: event.type });
+      return undefined;
+    }
+    return {
+      icon: event.data.icon ?? ICONS.operationStart.icon,
+      level: ICONS.operationStart.level,
+      message: event.data.name ?? event.data.key,
+      idSuffix: `${event.data.key}:start`,
+    };
+  }
+  if (Trace.isOfType(Trace.OperationEnd, event)) {
+    if (!Schema.is(Trace.OperationEnd.schema)(event.data)) {
+      log('invalid trace event', { type: event.type });
+      return undefined;
+    }
+    // A `RunAgainError` (Operation.runAgain) is a scheduler yield, not a hard error: the trace records
+    // it as a failure tagged with the run-again error code, but it will be re-invoked. Detect it here
+    // and present it as a distinct warn-level state rather than folding it into failure. Fall back to
+    // the legacy message for events persisted before `errorCode` existed.
+    const incomplete =
+      event.data.outcome === 'failure' &&
+      (event.data.errorCode === RUN_AGAIN_ERROR_CODE ||
+        (event.data.errorCode === undefined && event.data.error === RUN_AGAIN_MESSAGE));
+    const presentation =
+      event.data.outcome === 'success'
+        ? { icon: ICONS.operationEndSuccess.icon, level: ICONS.operationEndSuccess.level, suffix: '' }
+        : incomplete
+          ? {
+              icon: ICONS.operationEndIncomplete.icon,
+              level: ICONS.operationEndIncomplete.level,
+              suffix: ' - Incomplete',
+            }
+          : { icon: ICONS.operationEndError.icon, level: ICONS.operationEndError.level, suffix: ' - Error' };
+    return {
+      icon: event.data.icon ?? presentation.icon,
+      level: presentation.level,
+      message: `${event.data.name ?? event.data.key}${presentation.suffix}`,
+      idSuffix: `${event.data.key}:end`,
+    };
+  }
+  return undefined;
+};
+
+export type CollectProcessActivityOptions = {
+  /**
+   * When set, messages with a `conversationId` that disagrees are excluded.
+   * Messages without `conversationId` still match when their pid is in the subtree.
+   */
+  conversationId?: string;
+  eventLimit?: number;
+};
+
+/**
+ * Collects human-readable activity lines for a process subtree (root pid and descendants).
+ * Used to surface live sub-agent status in the task list.
+ */
+export const collectProcessActivityLines = (
+  messages: readonly Trace.Message[],
+  rootPid: string,
+  options: CollectProcessActivityOptions = {},
+): string[] => {
+  const { conversationId, eventLimit = 50 } = options;
+  const descendantPids = collectDescendantPids(messages, rootPid);
+  const filtered = messages.filter((message) => {
+    const pid = message.meta.pid;
+    if (!pid || !descendantPids.has(pid)) {
+      return false;
+    }
+    const metaConvId = message.meta.conversation
+      ? EID.getEntityId(EID.parse(message.meta.conversation.uri))
+      : undefined;
+    if (conversationId && metaConvId !== undefined && metaConvId !== conversationId) {
+      return false;
+    }
+    return true;
+  });
+
+  const events = filtered
+    .flatMap((message) => Trace.flatten(message))
+    .sort((left, right) => left.timestamp - right.timestamp)
+    .slice(-eventLimit);
+
+  const toolCallContext = buildToolCallContext(filtered);
+  const lines: string[] = [];
+  for (const event of events) {
+    const presentation = presentEvent(event, toolCallContext);
+    if (presentation) {
+      lines.push(presentation.message);
+    }
+  }
+  return lines;
+};
+
+/**
+ * Derives a single in-flight status line from durable trace when ephemeral subscription
+ * is unavailable (e.g. between partial blocks or while a child operation is running).
+ */
+export const deriveInFlightActivityLine = (
+  messages: readonly Trace.Message[],
+  rootPid: string,
+  options: CollectProcessActivityOptions = {},
+): string | undefined => {
+  const { conversationId, eventLimit = 50 } = options;
+  const descendantPids = collectDescendantPids(messages, rootPid);
+  const filtered = messages.filter((message) => {
+    const pid = message.meta.pid;
+    if (!pid || !descendantPids.has(pid)) {
+      return false;
+    }
+    const metaConvId = message.meta.conversation
+      ? EID.getEntityId(EID.parse(message.meta.conversation.uri))
+      : undefined;
+    if (conversationId && metaConvId !== undefined && metaConvId !== conversationId) {
+      return false;
+    }
+    return true;
+  });
+
+  const events = filtered
+    .flatMap((message) => Trace.flatten(message))
+    .sort((left, right) => left.timestamp - right.timestamp)
+    .slice(-eventLimit);
+
+  const openOperations = new Map<string, { name: string; timestamp: number }>();
+  let agentRequestOpen = false;
+  let lastLine: string | undefined;
+
+  for (const event of events) {
+    const pid = event.meta.pid ?? rootPid;
+    if (Trace.isOfType(Trace.OperationStart, event)) {
+      const key = `${pid}:${event.data.key}`;
+      const name = event.data.name ?? event.data.key;
+      openOperations.set(key, { name, timestamp: event.timestamp });
+      lastLine = `${name}...`;
+      continue;
+    }
+    if (Trace.isOfType(Trace.OperationEnd, event)) {
+      openOperations.delete(`${pid}:${event.data.key}`);
+      continue;
+    }
+    if (Trace.isOfType(Trace.AgentRequestBegin, event)) {
+      agentRequestOpen = true;
+      lastLine = 'Generating...';
+      continue;
+    }
+    if (Trace.isOfType(Trace.AgentRequestEnd, event)) {
+      agentRequestOpen = false;
+    }
+  }
+
+  if (agentRequestOpen) {
+    return 'Generating...';
+  }
+
+  const latestOperation = [...openOperations.values()].sort((left, right) => right.timestamp - left.timestamp)[0];
+  if (latestOperation) {
+    return `${latestOperation.name}...`;
+  }
+
+  return lastLine;
+};
+
+const collectDescendantPids = (messages: readonly Trace.Message[], rootPid: string): Set<string> => {
+  const pids = new Set([rootPid]);
+  let expanded = true;
+  while (expanded) {
+    expanded = false;
+    for (const message of messages) {
+      const pid = message.meta.pid;
+      const parentPid = message.meta.parentPid;
+      if (pid && parentPid && pids.has(parentPid) && !pids.has(pid)) {
+        pids.add(pid);
+        expanded = true;
+      }
+    }
+  }
+  return pids;
+};
+
+const isPendingToolCallEvent = (event: Trace.FlatEvent, toolCallContext: ToolCallContext): boolean => {
+  if (!Trace.isOfType(Trace.CompleteBlock, event)) {
+    return false;
+  }
+  if (event.data.block._tag !== 'toolCall') {
+    return false;
+  }
+  return !toolCallContext.resultByCallId.has(event.data.block.toolCallId);
+};
+
+/**
+ * A span is completed when its last recorded event is a matching end boundary.
+ */
+const isCompletedSpan = (span: Span): boolean => {
+  if (span.id === ROOT_SPAN_ID) {
+    return false;
+  }
+  const lastEvent = span.events[span.events.length - 1];
+  return lastEvent !== undefined && isSpanEndEvent(lastEvent);
+};
+
+/**
+ * A span is "collapsible" when it would otherwise render as an empty fork-and-merge:
+ * exactly two events that form a begin/end pair and no child sub-spans. In that case
+ * we emit a single commit for the end event on the parent branch.
+ *
+ * When `collapseCompletedSpans` is enabled, any completed span collapses to that single
+ * end commit — middle events, child sub-spans, and the begin fork are all omitted.
+ *
+ * A *pending* span (one whose end event has not yet been recorded) is never collapsed:
+ * its trailing events should keep rendering as middle commits on the span's own branch
+ * — never as a fake "end" commit on the parent branch.
+ *
+ * Both nested spans and top-level spans (whose parent is the synthetic root) are eligible
+ * once they have completed: a span with no inner activity is collapsed regardless of where
+ * it sits in the tree.
+ */
+const isCollapsibleSpan = (span: Span, parent: Span | null, collapseCompletedSpans: boolean): boolean => {
+  if (span.id === ROOT_SPAN_ID) {
+    return false;
+  }
+  if (parent === null) {
+    return false;
+  }
+  if (span.events.length === 2 && span.children.length === 0) {
+    const firstEvent = span.events[0];
+    const lastEvent = span.events[span.events.length - 1];
+    if (isSpanBeginEvent(firstEvent) && isSpanEndEvent(lastEvent)) {
+      return true;
+    }
+  }
+  if (collapseCompletedSpans && isCompletedSpan(span)) {
+    return true;
+  }
+  return false;
+};
+
+/**
+ * Converts a span tree into a flat list of commits + branches suitable for `Timeline` rendering.
+ *
+ * For every span the algorithm:
+ *  - emits the **first** event as a "begin" commit on the parent span's branch (fork);
+ *  - emits **middle** events as commits on the span's own branch;
+ *  - emits the **last** event as an "end" commit on the parent span's branch with two parents
+ *    (the begin commit and the last commit on the span's own branch — a merge).
+ *
+ * Collapsible spans (`isCollapsibleSpan`) emit only the end commit on the parent branch with
+ * a single parent — a tidier rendering for sub-operations that have no inner detail.
+ *
+ * Events are processed in categorical span-tree order: each span's begin events, its child
+ * subtrees (depth-first), then its remaining events. Active-process running rows are inserted
+ * at the end of each matching span block — not appended after the entire tree.
+ */
+const spanTreeToCommits = (
+  root: Span,
+  activeProcesses: readonly Process.Info[],
+  toolCallContext: ToolCallContext,
+  collapseCompletedSpans: boolean,
+): { branches: string[]; commits: Commit[]; details: ExecutionGraphDetailsMap } => {
+  const builder = new GraphBuilder();
+  const details: ExecutionGraphDetailsMap = {};
+  builder.addBranch(MAIN_BRANCH);
+
+  // Build a child → parent lookup using the tree's own structure (already correctly parented
+  // when the tree was constructed, including sequential spans of the same process).
+  const parentBySpan = new Map<Span, Span | null>();
+  parentBySpan.set(root, null);
+  const indexParents = (span: Span): void => {
+    for (const child of span.children) {
+      parentBySpan.set(child, span);
+      indexParents(child);
+    }
+  };
+  indexParents(root);
+
+  const findParentSpan = (span: Span): Span | null => parentBySpan.get(span) ?? null;
+
+  const collapsedSpanIds = new Set<string>();
+  walkSpanTree(root, (span) => {
+    if (isCollapsibleSpan(span, findParentSpan(span), collapseCompletedSpans)) {
+      collapsedSpanIds.add(span.id);
+    }
+  });
+
+  const isUnderCollapsedAncestor = (span: Span): boolean => {
+    let ancestor = findParentSpan(span);
+    while (ancestor) {
+      if (collapsedSpanIds.has(ancestor.id)) {
+        return true;
+      }
+      ancestor = findParentSpan(ancestor);
+    }
+    return false;
+  };
+
+  // The branch name for a span is its pid — multiple sequential spans of the same process
+  // (e.g. successive agent requests in one session) share a branch so they reuse a single lane.
+  const branchOf = (span: Span | null): string => {
+    if (!span || span.id === ROOT_SPAN_ID) {
+      return MAIN_BRANCH;
+    }
+    return span.meta.pid ?? span.id;
+  };
+
+  // Track the id of the begin commit for each non-collapsible span so the end commit can merge into it.
+  const beginCommitIdBySpan = new Map<string, string>();
+
+  // Selector that returns "the most recent commit in this span's structural context".
+  //
+  // The walk is structural (pid/parentPid), not topological: at each ancestor, we prefer
+  //   1) the last commit on that span's own branch, then
+  //   2) that span's begin commit (the fork point on its parent branch),
+  //   3) and only then recurse into the parent span.
+  //
+  // Crucially, we never silently slip onto a *sibling* span's commit on a shared ancestor
+  // branch. E.g. if a sub-span of agent A fires before A has any middle commits, we anchor
+  // to A.begin — not to whatever unrelated commit happens to be the latest on main.
+  // This keeps fork edges visually attached to the correct span even when sibling top-level
+  // spans (different pids) overlap in time on main.
+  const lastInSpanContext = (span: Span | null): CommitSelector => {
+    if (!span || span.id === ROOT_SPAN_ID) {
+      return CommitSelector.branch(MAIN_BRANCH).pipe(CommitSelector.compose(CommitSelector.last()));
+    }
+    const ownBranch = branchOf(span);
+    const beginId = beginCommitIdBySpan.get(span.id);
+    return CommitSelector.firstOf(
+      CommitSelector.branch(ownBranch).pipe(CommitSelector.compose(CommitSelector.last())),
+      beginId ? CommitSelector.id(beginId) : CommitSelector.filter(() => false),
+      lastInSpanContext(findParentSpan(span)),
+    );
+  };
+
+  const lastCommitIdBySpan = new Map<string, string>();
+  let globalIndex = 0;
+  const insertedRunningPids = new Set<string>();
+  const activeProcessByPid = new Map(activeProcesses.map((process) => [process.pid, process]));
+
+  const emitRunningIndicator = (pid: Process.ID): void => {
+    if (insertedRunningPids.has(pid)) {
+      return;
+    }
+
+    const process = activeProcessByPid.get(pid);
+    if (!process) {
+      return;
+    }
+
+    if (
+      Process.isHarnessHost(process) &&
+      Option.isSome(Annotation.getDictionary(process.params.annotations, Process.TargetAnnotation)) &&
+      (process.state === Process.State.RUNNING || process.state === Process.State.HYBERNATING)
+    ) {
+      builder.addCommit({
+        id: `running:${process.pid}`,
+        branch: process.pid,
+        // Falls back to the tail of main: a completed request collapses onto main, leaving the
+        // agent's own branch empty, and a parentless spinner draws as a second, disconnected root.
+        parents: builder.computeParents(
+          CommitSelector.firstOf(
+            CommitSelector.branch(process.pid).pipe(CommitSelector.compose(CommitSelector.last())),
+            CommitSelector.branch(MAIN_BRANCH).pipe(CommitSelector.compose(CommitSelector.last())),
+          ),
+        ),
+        icon: ICONS.agentRequestRunning.icon,
+        level: ICONS.agentRequestRunning.level,
+        message: 'Generating...',
+        timestamp: new Date(),
+        tags: [SHIMMER_EFFECT_TAG],
+      });
+      insertedRunningPids.add(pid);
+    } else if (process.state === Process.State.RUNNING && builder.hasBranch(process.pid)) {
+      builder.addCommit({
+        id: `running:${process.pid}`,
+        branch: process.pid,
+        parents: builder.computeParents(
+          CommitSelector.branch(process.pid).pipe(CommitSelector.compose(CommitSelector.last())),
+        ),
+        icon: ICONS.processRunning.icon,
+        level: ICONS.processRunning.level,
+        message: 'Running...',
+        timestamp: new Date(),
+        tags: [SHIMMER_EFFECT_TAG],
+      });
+      insertedRunningPids.add(pid);
+    }
+  };
+
+  const emitEventCommit = (span: Span, event: Trace.FlatEvent, eventIndex: number): void => {
+    const presentation = presentEvent(event, toolCallContext);
+    if (!presentation) {
+      return;
+    }
+
+    // Classify based on event TYPE, not array index. A pending span's trailing
+    // middle event (e.g. a user message awaiting an agent response) must not be
+    // mistaken for the span's end event — otherwise it would render on the
+    // parent branch instead of the span's own branch.
+    const isBeginEvent = isSpanBeginEvent(event);
+    const isEndEvent = isSpanEndEvent(event);
+    const parentSpan = findParentSpan(span);
+    const collapsible = isCollapsibleSpan(span, parentSpan, collapseCompletedSpans);
+
+    // Descendants of a collapsed span emit no commits — inner activity is folded into the ancestor end row.
+    if (isUnderCollapsedAncestor(span)) {
+      return;
+    }
+
+    // Collapsed spans: skip every event except the end commit.
+    if (collapsible && !isEndEvent) {
+      return;
+    }
+
+    const parentBranch = branchOf(parentSpan);
+    const ownBranch = branchOf(span);
+
+    // A "process boundary" span is a concurrent child PROCESS (its own pid, differing from the
+    // parent's) with real sub-flow content (a middle event) — e.g. a delegated sub-agent. Such a
+    // span gets its own lane: it forks onto its own branch at begin and collapses back to main at
+    // end (so neither its lane nor its parent's lane dangles). A bare operation (begin+end only)
+    // collapses to a single commit and is NOT treated as a boundary — forking its transient begin
+    // mid-stream would flash a throwaway lane.
+    const ownPid = span.meta.pid;
+    const parentPid = parentSpan?.meta.pid;
+    const spanHasMiddle = span.events.some((spanEvent) => !isSpanBeginEvent(spanEvent) && !isSpanEndEvent(spanEvent));
+    const isProcessBoundary = ownPid != null && parentPid != null && ownPid !== parentPid && spanHasMiddle;
+
+    let branch: string;
+    let parents: string[];
+
+    if (span.id === ROOT_SPAN_ID) {
+      // Root-level events (no pid) attach sequentially to main.
+      branch = MAIN_BRANCH;
+      parents = builder.computeParents(lastInSpanContext(null));
+    } else if (collapsible) {
+      // Only the end event reaches here for collapsible spans.
+      // Anchor to the parent span's structural context so the fork attaches to the parent
+      // — not to a sibling span's commit that happens to be the latest on the shared ancestor.
+      branch = parentBranch;
+      parents = builder.computeParents(lastInSpanContext(parentSpan));
+    } else if (isBeginEvent) {
+      // Begin commit, anchored to the parent's structural context. A nested sub-span stays on the
+      // parent lane (only its middle events fork). A concurrent child process forks onto its own
+      // branch from this first event so it gets its own lane immediately.
+      branch = isProcessBoundary ? ownBranch : parentBranch;
+      parents = builder.computeParents(lastInSpanContext(parentSpan));
+    } else if (isEndEvent) {
+      // End commit: continues the parent branch chronologically and merges in own-branch work.
+      //
+      // Parent #1 is the *immediate predecessor* on the parent branch (not the matching begin
+      // commit). Pointing back to the begin commit creates a visual edge that skips over any
+      // sibling span's commits emitted between begin and end — e.g. when two top-level Routine
+      // spans overlap on main, R1.end would otherwise draw an arrow back to R1.begin that
+      // crosses over R2.begin. Anchoring to the previous main commit keeps main linear.
+      //
+      // A concurrent child process collapses all the way back to MAIN (merging its own branch),
+      // rather than to its parent's branch: the parent (e.g. a supervisor whose turn already merged
+      // to main) would otherwise gain commits after its own merge and never re-collapse — leaving a
+      // dangling lane after the child finishes.
+      branch = isProcessBoundary ? MAIN_BRANCH : parentBranch;
+      parents = builder.computeParents(
+        CommitSelector.unionAll(
+          CommitSelector.branch(branch).pipe(CommitSelector.compose(CommitSelector.last())),
+          CommitSelector.branch(ownBranch).pipe(CommitSelector.compose(CommitSelector.last())),
+        ),
+      );
+    } else {
+      // Middle event: continue the span's own branch; fall back to span's own context so the
+      // first middle event of a span forks from the span's begin commit, not from a sibling's
+      // commit on an ancestor branch.
+      branch = ownBranch;
+      parents = builder.computeParents(lastInSpanContext(span));
+    }
+
+    const commitIndex = globalIndex++;
+    const commitId = formatCommitId(span, commitIndex, presentation.idSuffix);
+    // A pending tool call still in flight gets Timeline shimmer styling.
+    const shimmer = isPendingToolCallEvent(event, toolCallContext);
+    const commit: Commit = {
+      id: commitId,
+      branch,
+      parents,
+      timestamp: new Date(event.timestamp),
+      icon: presentation.icon,
+      level: presentation.level,
+      message: presentation.message,
+      ...(shimmer && { tags: [SHIMMER_EFFECT_TAG] }),
+    };
+    builder.addCommit(commit);
+    details[commitId] = event;
+    lastCommitIdBySpan.set(span.id, commitId);
+
+    // Record begin commit so a later end event can merge into it.
+    if (isBeginEvent && !collapsible && span.id !== ROOT_SPAN_ID) {
+      beginCommitIdBySpan.set(span.id, commitId);
+    }
+  };
+
+  const finishSpan = (span: Span): void => {
+    const pid = span.meta.pid;
+    if (pid) {
+      // Trace.Meta.pid is plain string (avoids circular dep); construct brand here.
+      emitRunningIndicator(Process.ID.make(pid));
+    }
+
+    if (span.id === ROOT_SPAN_ID || isCompletedSpan(span)) {
+      return;
+    }
+
+    if (pid && insertedRunningPids.has(pid)) {
+      return;
+    }
+
+    const lastCommitId = lastCommitIdBySpan.get(span.id);
+    if (lastCommitId) {
+      builder.addTag(lastCommitId, SHIMMER_EFFECT_TAG);
+    }
+  };
+
+  const emitSpanCommits = (span: Span): void => {
+    for (let eventIndex = 0; eventIndex < span.events.length; eventIndex += 1) {
+      const event = span.events[eventIndex]!;
+      if (isSpanBeginEvent(event)) {
+        emitEventCommit(span, event, eventIndex);
+      }
+    }
+
+    for (const child of span.children) {
+      emitSpanCommits(child);
+    }
+
+    for (let eventIndex = 0; eventIndex < span.events.length; eventIndex += 1) {
+      const event = span.events[eventIndex]!;
+      if (!isSpanBeginEvent(event)) {
+        emitEventCommit(span, event, eventIndex);
+      }
+    }
+
+    finishSpan(span);
+  };
+
+  emitSpanCommits(root);
+
+  for (const process of activeProcesses) {
+    emitRunningIndicator(process.pid);
+  }
+
+  const { commits, branches } = builder.build();
+  return { commits, branches, details };
+};
+
+const formatCommitId = (span: Span, globalIndex: number, suffix?: string): string => {
+  const base = `${span.id}:${globalIndex}`;
+  return suffix ? `${base}:${suffix}` : base;
+};
+
+const trimText = (text: string) => text.slice(0, 100).trim().split('\n')[0];
+
+type Falsy = false | null | undefined;
+
+export interface CommitSelector extends Pipeable.Pipeable {
+  select: (commits: Commit[]) => Commit[];
+}
+
+export const CommitSelector = {
+  make: (select: CommitSelector['select']): CommitSelector => ({
+    select,
+    pipe(...args: any) {
+      return Pipeable.pipeArguments(this, args);
+    },
+  }),
+
+  identity: (): CommitSelector => CommitSelector.make((commits) => commits),
+
+  /**
+   * Selects commits that match the given predicate.
+   */
+  filter: (predicate: (commit: Commit) => unknown): CommitSelector =>
+    CommitSelector.make((commits) => commits.filter(predicate)),
+
+  /**
+   * Selects commits by id.
+   */
+  id: (id: string): CommitSelector => CommitSelector.filter((commit) => commit.id === id),
+  /**
+   * Selects commits by tag.
+   */
+  tag: (tag: string | Falsy): CommitSelector => CommitSelector.filter((commit) => tag && commit.tags?.includes(tag)),
+  /**
+   * Selects commits by if any of the given tags are present.
+   */
+  anyTags: (tags: (string | Falsy)[]): CommitSelector =>
+    CommitSelector.filter((commit) => tags.some((tag) => tag && commit.tags?.includes(tag))),
+  /**
+   * Selects commits by branch.
+   */
+  branch: (branch: string | Falsy): CommitSelector =>
+    CommitSelector.filter((commit) => branch && commit.branch === branch),
+
+  /**
+   * Chains two selectors together, applying the second selector to the result of the first.
+   *
+   * Example:
+   *
+   * ```
+   * CommitSelector.tag('tag').pipe(CommitSelector.compose(CommitSelector.branch('main')));
+   * ```
+   */
+  compose:
+    (next: CommitSelector) =>
+    (prev: CommitSelector): CommitSelector =>
+      CommitSelector.make((commits) => next.select(prev.select(commits))),
+
+  /**
+   * If `prev` selector matches no commits, return `next` selector, otherwise return `prev` selector.
+   * Same as `CommitSelector.firstOf(prev, next)`.
+   *
+   * Example:
+   *
+   * ```
+   * CommitSelector.tag('tag').pipe(CommitSelector.orElse(CommitSelector.branch('main')));
+   * ```
+   */
+  orElse:
+    (next: CommitSelector) =>
+    (prev: CommitSelector): CommitSelector =>
+      CommitSelector.make((commits) => {
+        const selected = prev.select(commits);
+        if (selected.length > 0) {
+          return selected;
+        }
+        return next.select(commits);
+      }),
+
+  /**
+   * Selects commits that match either of the given selectors.
+   */
+  andAlso:
+    (next: CommitSelector) =>
+    (prev: CommitSelector): CommitSelector =>
+      CommitSelector.unionAll(prev, next),
+
+  /**
+   * Selects the first n commits.
+   */
+  first: (n: number = 1): CommitSelector => CommitSelector.make((commits) => commits.slice(0, n)),
+  /**
+   * Selects the last n commits (reverses the order of the commits).
+   */
+  last: (n: number = 1): CommitSelector => CommitSelector.make((commits) => commits.toReversed().slice(0, n)),
+  /**
+   * Selects commits that do not match the given selector.
+   */
+  not: (selector: CommitSelector): CommitSelector =>
+    CommitSelector.make((commits) => {
+      const selected = selector.select(commits);
+      return commits.filter((commit) => !selected.includes(commit));
+    }),
+
+  /**
+   * Selects commits that match any of the given selectors.
+   */
+  unionAll: (...selectors: CommitSelector[]): CommitSelector =>
+    CommitSelector.make((commits) => {
+      return Array.dedupeWith(
+        selectors.flatMap((selector) => selector.select(commits)),
+        (a, b) => a.id === b.id,
+      );
+    }),
+
+  /**
+   * Selects commits that match all of the given selectors.
+   */
+  intersectAll: (...selectors: CommitSelector[]): CommitSelector =>
+    CommitSelector.make((commits) => {
+      const selected = selectors.map((selector) => selector.select(commits));
+      if (selected.length === 0) {
+        return [];
+      }
+      return selected[0].filter((commit) => selected.every((selected) => selected.some((c) => c.id === commit.id)));
+    }),
+
+  /**
+   * Returns the result of the first selector that matches any commits.
+   */
+  firstOf: (...selectors: CommitSelector[]): CommitSelector =>
+    CommitSelector.make((commits) => {
+      for (const selector of selectors) {
+        const selected = selector.select(commits);
+        if (selected.length > 0) {
+          return selected;
+        }
+      }
+      return [];
+    }),
+};
+
+class GraphBuilder {
+  #commits: Commit[] = [];
+  #branches = new Set<string>();
+
+  findCommits(selector: CommitSelector): Commit[] {
+    return selector.select(this.#commits);
+  }
+
+  hasBranch(branch: string): boolean {
+    return this.#branches.has(branch);
+  }
+
+  addCommit(commit: Commit) {
+    this.addBranch(commit.branch);
+    this.#commits.push(commit);
+  }
+
+  addTag(commitId: string, tag: string) {
+    const index = this.#commits.findIndex((commit) => commit.id === commitId);
+    if (index < 0) {
+      return;
+    }
+    const commit = this.#commits[index]!;
+    if (commit.tags?.includes(tag)) {
+      return;
+    }
+    this.#commits[index] = { ...commit, tags: [...(commit.tags ?? []), tag] };
+  }
+
+  /**
+   * Computes parents — picks first matching commit's id.
+   */
+  computeParents(selector: CommitSelector): string[] {
+    return Array.dedupe(selector.select(this.#commits).map((commit) => commit.id));
+  }
+
+  addBranch(branch: string) {
+    this.#branches.add(branch);
+  }
+
+  /**
+   * Removes duplicate commits and dangling parents.
+   */
+  doctor() {
+    this.#commits = pipe(
+      this.#commits,
+      Array.dedupeWith((a, b) => a.id === b.id),
+      Array.map(
+        Struct.evolve({
+          parents: (parents) =>
+            parents ? Array.filter(parents, (id) => this.#commits.some((commit) => commit.id === id)) : undefined,
+        }),
+      ),
+    );
+  }
+
+  build() {
+    this.doctor();
+    return {
+      commits: this.#commits,
+      branches: [...this.#branches],
+    };
+  }
+}