trace: group related runs and show persisted parent-child lineage

[alectimison-maker]

Summary

The trace recorder now persists session identity and parent-run metadata, and the Traces page can display per-run statistics and step-level trajectory details. Related runs are still presented as a flat list, so users cannot follow a browser run into a cloud execution or replay.

This issue proposes the next focused Traces improvement: group related runs by session and render their persisted parent-child relationships.

User-visible outcome

• Runs belonging to one session appear together.
• Parent and child runs are shown in an expandable hierarchy.
• Selecting a node opens the existing run timeline, statistics, trajectory table, compare action, and export action.
• Missing or legacy relationships remain usable as standalone roots.

Proposed design

Lineage model

Use persisted run records only:

• Session identity remains the existing conversation/session identifier.
• runId identifies one recorded execution.
• parentRunId identifies the run that launched a derived execution.
• parentSessionId remains metadata for cross-session relationships.
• Build the hierarchy with a pure function over records; do not depend on live agent state.

The tree builder should:

• attach children by parentRunId;
• sort siblings deterministically by startedAt then runId;
• treat missing parents as visible roots with an orphan marker;
• guard against duplicate IDs and cycles;
• tolerate legacy records with missing lineage fields.

Future telemetry export identity

To keep the model usable outside the UI, propose:

• one logical session maps to one OTLP trace;
• each run maps to one span in that trace;
• a derived run uses the parent run span as parentSpanId;
• step rows are represented as span events initially; promote them to child spans only if stable step identity and timing are available;
• when session or parent metadata is missing, keep the current deterministic hash fallback.

This issue asks maintainers to confirm this mapping; it does not change the exporter yet.

Scope

In scope:

• Session grouping and lineage navigation in Chrome and Firefox.
• A pure lineage-tree helper with unit tests.
• UI integration without changing event payloads or adding a new persistence table.
• Regression coverage for the current timeline, statistics, trajectory, compare, export, and refresh behavior.

Out of scope:

• Changing the recorder event schema.
• Redesigning session statistics.
• Implementing the OTLP mapping.
• Loading unbounded session history in one request.

Compatibility and privacy

• Existing records without lineage metadata remain readable.
• IDs only; no message content should be copied into lineage nodes.
• Unknown event kinds and existing export behavior remain unchanged.
• Large sessions should use a bounded or paged query, or clearly indicate incomplete loading.

Acceptance criteria

• Runs with the same session identity are grouped without replaying their event streams.
• Parent-child links are derived from persisted runId and parentRunId values.
• Orphans, duplicate IDs, cycles, and legacy records do not break rendering.
• Selecting any node preserves the existing timeline, statistics, trajectory, compare, export, and refresh workflows.
• Chrome and Firefox behavior is covered by equivalent tests.
• The proposed session/run/step identity mapping is documented in the implementation or follow-up export issue before OTLP changes begin.

References

• Builds on trace: session lineage fields (parentRunId/parentSessionId/delegationDepth) + runs index #2870 and trace: plumb parentRunId from cloud_run and replay entry points #2871, which added and populated persisted lineage metadata.
• Complements the step trajectory view in feat(trace): add step trajectory table #2893 and session statistics in feat(trace): add session statistics without event replay #2899.

Maintainer questions

1. Is the proposed mapping of session to trace, run to span, and step to event the desired export contract?
2. Should step-level spans remain deferred until stable step identifiers and timing semantics are available?
3. Is an expandable hierarchy the preferred Traces interaction, or should the first version use a compact grouped list with parent links?

[esokullu]

Thanks — this is the right next Traces increment. The proposed persisted-record-only scope looks good.

1. Telemetry mapping: approved with one clarification:
   • one logical session → one OTLP trace
   • each run → one span
   • for same-session lineage, parentRunId → parentSpanId
   • if parentSessionId differs from the child session, that is a cross-trace relationship and must not be encoded as parentSpanId; use an OTLP Span Link when exporter work lands, while preserving the lineage IDs as WebBrain attributes in the meantime
2. Steps: keep step rows as span events for now. Defer step-level child spans until stable step IDs and unambiguous persisted start/end timing exist.
3. UI: use the expandable hierarchy for the first version, grouped by session and collapsed by default. Selecting any run node should continue to drive the existing timeline/statistics/trajectory/compare/export detail surface.

A few implementation constraints:

• Never drop a persisted record because of duplicate IDs, a missing parent, or a cycle. Do not attach through an ambiguous duplicate; surface affected records as visible roots with an orphan/cycle marker.
• Attach a parent only when the resolved parent record is present in the bounded loaded result. Otherwise keep the lineage reference visible without implying that the full tree was loaded.
• Keep sibling ordering deterministic: startedAt, then runId.
• Show an incomplete-lineage indicator when pagination or the query bound may have omitted relatives.
• Preserve Chrome/Firefox parity and all current refresh, selection, timeline, statistics, trajectory, compare, and export behavior.

The scope and acceptance criteria are otherwise good. Please keep the OTLP exporter changes as a follow-up after the persisted-record helper and UI work land.