fix(traceview): make ReferenceId match the reference hierarchy leaf

[jepadil23]

• Bug: a span's top-level ReferenceId was resolved from a source unrelated to the id the runtime actually stamps, so it disagreed with both the referenceId attribute and the referenceHierarchy on every span.
• What the runtime does: uipath-agents-python agent.py:135-151 takes one id — agent_definition.id, else UIPATH_PROCESS_UUID — and uses it for both the referenceId attribute and the ("agent", agent_id, …) hierarchy entry. Those two always agreed.
• What the conversion layer did: _span_utils.py wrote attributes_dict["agentId"] = resolve_project_id() — a project id (uipath.json#id → UIPATH_AGENT_ID → UIPATH_PROJECT_ID → PROJECT_KEY, the same helper telemetry/_track.py uses to report project_id) — then computed reference_id = agentId or referenceId. The or ordering meant the project id always beat the agent id the runtime had stamped.
• Fix: precedence is now referenceId attribute → hierarchy leaf → agentId.
• Why referenceId first, not the leaf: the runtime stamps referenceId and pushes that same id onto the hierarchy, so the leaf is a consequence of the reference id, not its source. When a service fails to push its own entry (agent.py:149-150 falls back to parent_ctx on a non-UUID id), the hierarchy is still non-empty and its leaf holds the caller's id — deriving from it would file the span under maestro instead of the agent.
• Why the leaf at all: it covers producers that push onto the hierarchy without stamping the attribute, e.g. uipath-langchain-python's langgraph entry, which otherwise falls through to the project id and diverges the same way.
• Blast radius: agentId as a span attribute is untouched; only the top-level ReferenceId changes, and only for spans carrying a referenceId attribute or a hierarchy. Producers that emit neither keep the current behaviour.

Why it went unnoticed

resolve_project_id() returns None in a bare local checkout (no uipath.json#id, no env vars), so reference_id fell through to referenceId and matched. uipath init then backfills uipath.json#id — with str(uuid.uuid4()) when neither UIPATH_PROJECT_ID nor .uipath/.telemetry.json#ProjectKey is present (cli_init.py:436,445). From that point on a random GUID outranks the real agent id on every emitted span.

Behaviour

With uipath.json#id = 1111…, agent.json#id = 2222…, caller 3333…:

span	before	after
agent run (referenceId + hierarchy)	1111…	2222…
langgraph (hierarchy only, no attr)	1111…	2222…
push failed — leaf is the caller	1111…	2222… (not 3333…)
no hierarchy, no referenceId	1111…	1111… unchanged

Tests

• Two cases in TestReferenceIdResolution asserted the old precedence and were updated; the class docstring now states the source/consequence relationship and why agentId is last.
• Added cases for leaf-as-fallback, the unpushed-entry misattribution guard, malformed hierarchy JSON, and a leaf with no referenceId.
• New TestReferenceIdMatchesHierarchyLeaf pins the invariant end-to-end against a populated project id.
• uipath-platform suite green; ruff + mypy clean.

Note

agentId as a span attribute still carries a project id (_span_utils.py:471). That is a separate pre-existing naming problem and is deliberately out of scope here — changing what the backend receives for agentId is a bigger call than this fix.

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟢 Approval recommended

All reviewed changes align with the intended fix and regression coverage.

Review effort: Lite
Findings: None

What changed in this PR

Fixes span conversion so top-level ReferenceId matches the innermost reference hierarchy entry instead of the project ID.

Changes:

• Prioritizes the hierarchy leaf, then referenceId, then agentId.
• Reuses parsed hierarchy data for ID resolution and context.
• Adds regression tests for precedence and ID mismatches.

File	Description
packages/​uipath-platform/​tests/​services/​test_span_utils.py	Updates and expands reference ID resolution tests.
packages/​uipath-platform/​tests/​services/​test_reference_context.py	Adds hierarchy and ReferenceId consistency tests.
packages/​uipath-platform/​src/​uipath/​platform/​common/​_span_utils.py	Implements hierarchy-aware reference ID resolution.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
94.7% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[jepadil23]

Superseded. ReferenceId resolution predates the reference hierarchy and works as intended — changing it to satisfy the newer feature is the wrong direction, and it is a wire-visible change to every span. The divergence belongs at the push sites instead, where the hierarchy entry should carry the id ReferenceId already resolves to:

• UiPath/uipath-agents-python#768 (agent entry)
• fix(traceview): push the id ReferenceId resolves to onto the hierarchy uipath-langchain-python#1115 (langgraph entry)

No change to uipath-python is needed.