feat(agents): root Relay traces at the platform session [ASTD-534]

[marcusds]

What

Each turn of a platform agent session now carries relay_session_root: a UUIDv5 of the platform session id under a fixed namespace, so every turn of one session sends the same value and different sessions never collide. Platform session ids are not UUIDs, so the session id itself cannot be used.

The value rides on the platform's invocation requests (FabricInvocationRequest, FabricOneShotRequest) through the session manager and is passed to Fabric as the typed RunRequest.relay_session_root field, only when set. caller_context is unchanged.

Why

Studio chats and other session-backed calls land in Intake as one session per turn. Relay 0.9 derives the ATIF session_id from the propagation root, and Fabric roots propagation at each request unless the caller supplies a session root. NVIDIA/NeMo-Fabric#358, merged for Fabric 0.5, adds that field; this sends it, so a conversation records as one Intake session with one trajectory per turn.

Dependencies and limits

• Takes effect once nemo-helix moves to Fabric 0.5. On Fabric 0.4 the Python RunRequest keeps the unknown field as an extra and Fabric's Rust core drops it, so this is inert and safe to merge before the bump.
• Deep Agents agents, including the Studio assistant, and mini-SWE-agent group by session. Hermes, Claude, and Codex agents keep one session per turn: their Relay integrations do not read the field.
• Stateless calls without X-Nemo-Session-Id are unchanged.

Still to land before this is ready

• Bump nemo-fabric* pins to >=0.5.0,<0.6.0 once Fabric 0.5 is published, relock, and run the agents plugin against it.
• Confirm Intake keeps one row per trajectory now that turns share a session_id: ClickHouse spans and the evaluation rollup group on session_id, and trajectory_id becomes the unique key.
• Verify against a running platform: two turns on one session give two traces under one session_id with distinct trajectory_id.

Verification

• test_fabric_server.py, test_fabric_runtime.py, test_fabric_session_manager.py: 102 passed. Covers a stable root per session and a distinct root per session, no root without a session, the session manager copying the field to the one-shot request, and invoke_fabric_runtime sending it on RunRequest only when set.
• Ruff, format, and ty clean on the changed files.

[datadog-official]

❌ Errors

Your PR has failed checks. Please review the issues below and take necessary action before merging.

🚦 2 Pipeline jobs failed

CI | CI status

View in Datadog · View in GitHub Actions

CI | Kind Gym agent-evaluate e2e

View in Datadog · View in GitHub Actions

Useful? React with 👍 / 👎

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 639cb52 | Docs | View more details | Give us feedback!}

[github-actions]

Suite	Lines Covered	Line Rate	Branch Rate
Unit Tests	51168/62980	81.2%	65.9%
Integration Tests	33162/60052	55.2%	26.3%