@dxos/react-ui-trace 0.11.1

package/src/execution-graph/index.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export {
+  type BuildExecutionGraphParams,
+  type CollectProcessActivityOptions,
+  CommitSelector,
+  type ExecutionGraph,
+  type ExecutionGraphDetailsMap,
+  buildExecutionGraph,
+  collectProcessActivityLines,
+  deriveInFlightActivityLine,
+} from './execution-graph.ts';
+export {
+  type EphemeralStatusUpdate,
+  estimateTokenCount,
+  formatPendingBlockStatus,
+  pendingStatusFromEphemeralMessage,
+  resolveEphemeralStatusUpdate,
+} from './pending-block-status.ts';
+export {
+  BEGIN_EVENT_TYPES,
+  type BuildSpanTreeOptions,
+  DEFAULT_SPAN_TIMEOUT_MS,
+  END_EVENT_TYPES,
+  ROOT_SPAN_ID,
+  type Span,
+  type SpanMeta,
+  buildSpanTree,
+  flattenSpanTree,
+  isSpanBeginEvent,
+  isSpanEndEvent,
+  walkSpanTree,
+} from './span-tree.ts';

package/src/execution-graph/pending-block-status.test.ts

@@ -0,0 +1,118 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import * as Trace from '@dxos/compute/Trace';
+
+import {
+  formatPendingBlockStatus,
+  pendingStatusFromEphemeralMessage,
+  resolveEphemeralStatusUpdate,
+} from './pending-block-status.ts';
+
+describe('formatPendingBlockStatus', () => {
+  test('formats pending text as generating tokens', ({ expect }) => {
+    const status = formatPendingBlockStatus({
+      _tag: 'text',
+      text: 'Hello world',
+      pending: true,
+    });
+    expect(status).toMatch(/^Generating \d+ tokens\.\.\.\.$/);
+  });
+
+  test('formats pending tool call with byte count', ({ expect }) => {
+    const status = formatPendingBlockStatus({
+      _tag: 'toolCall',
+      toolCallId: 'call-1',
+      name: 'create-document',
+      input: '{"title":"Haiku"}',
+      providerExecuted: false,
+      pending: true,
+    });
+    expect(status).toBe('Calling create-document (17 bytes)...');
+  });
+
+  test('returns undefined for completed blocks', ({ expect }) => {
+    expect(
+      formatPendingBlockStatus({
+        _tag: 'text',
+        text: 'Done',
+        pending: false,
+      }),
+    ).toBeUndefined();
+  });
+
+  test('formats operation input as calling with byte count', ({ expect }) => {
+    const status = pendingStatusFromEphemeralMessage(
+      ephemeralMessage([
+        {
+          type: Trace.OperationInput.key,
+          timestamp: Date.now(),
+          data: {
+            key: 'org.dxos.operation.assistantToolkit.getContext',
+            name: 'Get Agent Context',
+            input: { foo: 'bar' },
+          },
+        },
+      ]),
+    );
+    expect(status).toBe('Calling Get Agent Context (13 bytes)...');
+  });
+
+  test('leaves status unchanged (sticky) when partial block stream completes', ({ expect }) => {
+    expect(
+      resolveEphemeralStatusUpdate(
+        ephemeralMessage([
+          {
+            type: 'assistant.partialBlock',
+            timestamp: Date.now(),
+            data: {
+              messageId: 'msg-1',
+              role: 'assistant',
+              block: {
+                _tag: 'toolCall',
+                toolCallId: 'call-1',
+                name: 'update-tasks',
+                operationName: 'Update tasks',
+                input: '{}',
+                providerExecuted: false,
+                pending: false,
+              },
+            },
+          },
+        ]),
+      ),
+    ).toBe('unchanged');
+  });
+
+  test('suppresses raw routine ULID status updates', ({ expect }) => {
+    expect(
+      pendingStatusFromEphemeralMessage(
+        ephemeralMessage([
+          {
+            type: Trace.StatusUpdate.key,
+            timestamp: Date.now(),
+            data: { message: 'Running 01KVB9WBRG0000000000000000' },
+          },
+        ]),
+      ),
+    ).toBeUndefined();
+  });
+
+  test('keeps descriptive status updates', ({ expect }) => {
+    expect(
+      pendingStatusFromEphemeralMessage(
+        ephemeralMessage([
+          { type: Trace.StatusUpdate.key, timestamp: Date.now(), data: { message: 'Thinking about the plan' } },
+        ]),
+      ),
+    ).toBe('Thinking about the plan');
+  });
+});
+
+// `Trace.Message` is an ECHO object type, so a plain test literal does not structurally overlap it;
+// build the minimal ephemeral envelope the status helpers read via a single boundary cast.
+const ephemeralMessage = (events: readonly Trace.Event[]): Trace.Message =>
+  ({ meta: { pid: 'pid-1' }, isEphemeral: true, events }) as unknown as Trace.Message;

package/src/execution-graph/pending-block-status.ts

@@ -0,0 +1,88 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Trace from '@dxos/compute/Trace';
+import { type ContentBlock } from '@dxos/types';
+
+/**
+ * Approximate streamed token count from partial text (UTF-8 length / 4).
+ */
+export const estimateTokenCount = (text: string): number =>
+  Math.max(1, Math.ceil(new TextEncoder().encode(text).length / 4));
+
+const formatOperationInputStatus = (data: { key: string; name?: string; input: unknown }): string => {
+  const name = data.name ?? data.key;
+  const bytes = new TextEncoder().encode(JSON.stringify(data.input)).length;
+  return `Calling ${name} (${bytes} bytes)...`;
+};
+
+/** Raw routine status updates (e.g. `Running 01KVB9WBRG…`) carry an opaque ULID, not a useful label. */
+const ROUTINE_ULID_STATUS = /^Running [0-9A-HJKMNP-TV-Z]{26}$/i;
+
+/**
+ * Formats a pending assistant block for the delegated-task status line.
+ */
+export const formatPendingBlockStatus = (block: ContentBlock.Any): string | undefined => {
+  if (!block.pending) {
+    return undefined;
+  }
+
+  if (block._tag === 'text') {
+    return `Generating ${estimateTokenCount(block.text)} tokens....`;
+  }
+
+  if (block._tag === 'toolCall') {
+    const bytes = new TextEncoder().encode(block.input).length;
+    const name = block.operationName ?? block.name;
+    return `Calling ${name} (${bytes} bytes)...`;
+  }
+
+  return undefined;
+};
+
+/**
+ * Reads the latest pending partial block from an ephemeral trace message.
+ */
+export const pendingStatusFromEphemeralMessage = (message: Trace.Message): string | undefined => {
+  for (const event of message.events) {
+    if (Trace.isOfType(Trace.PartialBlock, event)) {
+      const status = formatPendingBlockStatus(event.data.block);
+      if (status) {
+        return status;
+      }
+      continue;
+    }
+
+    if (Trace.isOfType(Trace.OperationInput, event)) {
+      return formatOperationInputStatus(event.data);
+    }
+
+    if (Trace.isOfType(Trace.StatusUpdate, event)) {
+      const message = event.data.message?.trim();
+      // Suppress opaque routine ULID lines so descriptive partial-block / operation-input lines win.
+      if (!message || ROUTINE_ULID_STATUS.test(message)) {
+        continue;
+      }
+      return message;
+    }
+  }
+  return undefined;
+};
+
+export type EphemeralStatusUpdate = 'unchanged' | { readonly line: string };
+
+/**
+ * Maps an ephemeral trace message to a task-status update.
+ *
+ * The status line is "sticky": a message without a pending line (e.g. a completed block during an
+ * LLM-thinking gap) leaves the previous line in place rather than clearing it, so the row keeps
+ * showing the latest meaningful activity until a new line arrives or the subscription ends.
+ */
+export const resolveEphemeralStatusUpdate = (message: Trace.Message): EphemeralStatusUpdate => {
+  const line = pendingStatusFromEphemeralMessage(message);
+  if (line) {
+    return { line };
+  }
+  return 'unchanged';
+};

package/src/execution-graph/remote-snapshot.test.ts

@@ -0,0 +1,116 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, test } from 'vitest';
+
+import * as Trace from '@dxos/compute/Trace';
+import { Obj } from '@dxos/echo';
+
+import { buildExecutionGraph } from './execution-graph.ts';
+
+/**
+ * Regression for sub-operations collapsing onto `main` when the event window in `buildSpanTree`
+ * dropped the parent span's `operation.start`.
+ *
+ * The remote trace snapshot has 714 chronological events. The 4th `Run Routine` span hosts every
+ * `Create object` / `Add schema` / `List schemas` / `Query` / `Add to context` sub-operation.
+ * Its `operation.start` lives near the front of the stream (index 70). Before the fix, the
+ * default `eventLimit = 300` would `slice(-300)` away that begin event, leaving the sub-ops'
+ * `parentPid` lookup unsatisfied — they ended up as top-level collapsible spans rendering their
+ * end commits on `main`.
+ */
+describe('TracePanel remote snapshot', () => {
+  test('sub-operations land on their parent Routine branch, never on main', ({ expect }) => {
+    const messages = loadRemoteTraceMessages(REMOTE_SNAPSHOT);
+    const { commits } = buildExecutionGraph({ traceMessages: messages });
+
+    // Commits whose message starts with one of these names originate from sub-operations
+    // (Trace.OperationEnd) — every one should live on the Routine's branch, never on `main`.
+    const subOpPrefixes = ['Create object', 'Add schema', 'List schemas', 'Query', 'Add to context'];
+    const isSubOpEnd = (message: string | undefined): boolean =>
+      message !== undefined && subOpPrefixes.some((prefix) => message.startsWith(prefix));
+
+    const subOpCommits = commits.filter((commit) => isSubOpEnd(commit.message));
+    expect(subOpCommits.length).toBeGreaterThan(0);
+
+    const onMain = subOpCommits.filter((commit) => commit.branch === 'main');
+    expect(onMain).toEqual([]);
+
+    // All sub-op end commits share the parent Routine's pid as their branch.
+    const branches = new Set(subOpCommits.map((commit) => commit.branch));
+    expect(branches.size).toBe(1);
+    expect(branches.has('main')).toBe(false);
+  });
+
+  test('Routine end commits anchor to the previous main commit, not back to their own begin', ({ expect }) => {
+    // Regression: the multi-Routine snapshot has overlapping top-level Routine spans (R2 starts
+    // before R1 ends, R4 starts before R3 ends). Previously, R1.end's first parent was
+    // R1.begin (looked up by `beginCommitIdBySpan`), which drew an edge across R2.begin in the
+    // rendered timeline. The fix anchors end commits to the immediate predecessor on the
+    // parent branch (R2.begin) and treats the own-branch tail as a separate merge parent.
+    const messages = loadRemoteTraceMessages(MULTI_SNAPSHOT);
+    const { commits } = buildExecutionGraph({ traceMessages: messages });
+
+    const mainCommits = commits.filter((commit) => commit.branch === 'main');
+    // Sanity check: 4 begin + 4 end Run-Routine commits on main.
+    expect(mainCommits).toHaveLength(8);
+
+    // For each commit on main, its first parent (if any) must be a commit that appears
+    // *earlier* in the main commit sequence — no "skip-back" edges to an older begin commit.
+    const idToMainIndex = new Map(mainCommits.map((commit, index) => [commit.id, index]));
+    for (let index = 1; index < mainCommits.length; index += 1) {
+      const commit = mainCommits[index];
+      const onMainParents = (commit.parents ?? []).filter((parentId) => idToMainIndex.has(parentId));
+      expect(onMainParents.length).toBeGreaterThan(0);
+      for (const parentId of onMainParents) {
+        const parentIndex = idToMainIndex.get(parentId)!;
+        // Every parent on main must be the immediate predecessor (index - 1). An older parent
+        // would render an edge that crosses over the intervening commits.
+        expect(parentIndex).toBe(index - 1);
+      }
+    }
+  });
+});
+
+const REMOTE_SNAPSHOT = 'trace-timeline-remote.dx.json';
+const MULTI_SNAPSHOT = 'trace-timeline-multiple.dx.json';
+
+interface RawMessage {
+  meta?: Trace.Meta;
+  isEphemeral?: boolean;
+  events?: Array<{ type: string; timestamp: number; data: unknown }>;
+}
+
+const loadRemoteTraceMessages = (filename: string): Trace.Message[] => {
+  const snapshotPath = join(__dirname, '../testing/data', filename);
+  const json = JSON.parse(readFileSync(snapshotPath, 'utf8')) as unknown;
+
+  const messages: Trace.Message[] = [];
+  const visit = (node: unknown): void => {
+    if (Array.isArray(node)) {
+      node.forEach(visit);
+      return;
+    }
+    if (node === null || typeof node !== 'object') {
+      return;
+    }
+    const candidate = node as RawMessage & Record<string, unknown>;
+    if (Array.isArray(candidate.events) && candidate.meta && typeof candidate.meta === 'object') {
+      messages.push(
+        Obj.make(Trace.Message, {
+          meta: candidate.meta,
+          isEphemeral: candidate.isEphemeral ?? false,
+          events: candidate.events,
+        }),
+      );
+    }
+    for (const value of Object.values(node as Record<string, unknown>)) {
+      visit(value);
+    }
+  };
+  visit(json);
+  return messages;
+};