feat(traces): route governance endpoints via llmops base [PLT-106297]

[ashishupadhyay88]

What

Routes the two governance AgentTraces endpoints from the insightsrtm_ base to llmopstenant_/api:

Method	Before	After
getGovernanceDecisions()	insightsrtm_/Governance/agentic/traces	llmopstenant_/api/Governance/agentic/traces
getGovernanceSummary()	insightsrtm_/Governance/agentic/summary	llmopstenant_/api/Governance/agentic/summary

Scope change (breaking for these 2 methods)

The llmops governance endpoint is a facade that forwards the request to InsightsRTM internally. So the token must satisfy both hops:

• Traces.Api — to pass the llmops gateway.
• Insights.RealTimeData Insights OR.Folders.Read — for the internal forward to insightsrtm_ (same scopes the direct insightsrtm_ route always required).

Documented scope for both methods:

Insights.RealTimeData Insights OR.Folders.Read → Traces.Api Insights.RealTimeData Insights OR.Folders.Read

This is breaking: existing consumers must add Traces.Api to their external app (the InsightsRTM scopes were already required). docs/oauth-scopes.md updated.

E2E

Verified against a real external-app OAuth token in governancedevs/DefaultTenant:

• Token with only Traces.Api → passed the llmops gateway but 401 on the internal InsightsRTM forward (Failed to call insightsrtm_ … Unauthorized).
• Token with Traces.Api Insights.RealTimeData Insights OR.Folders.Read → both governance endpoints return 200 with data.

Files

Area	File
Endpoint	src/utils/constants/endpoints/agent-traces.ts (2 governance constants)
Docs	docs/oauth-scopes.md (scope for the 2 governance methods)

Note / open decision

llmops governance is a proxy to InsightsRTM — the migration adds a network hop and an extra required scope (Traces.Api) with no functional change versus calling insightsrtm_ directly. Keeping it because llmops is the canonical route going forward; flag if the extra scope burden isn't worth it.

TODO before ready-for-review

• Cloudflare Workers whitelist for llmopstenant_/api/Governance/agentic/* (browser consumers / E2E proxy).

🤖 Draft — pending Cloudflare whitelist + final sign-off.

[claude]

Review findings

File not in diff: tests/integration/shared/observability/traces/agent.integration.test.ts

Now that getGovernanceDecisions and getGovernanceSummary are routed to llmopstenant_ (which accepts PAT tokens with Traces.Api scope), the outer describe.skip.each and its justification comment are no longer accurate for those two methods.

Per CLAUDE.md: describe.skip is permitted only when the service does not support PAT auth.

Three things need updating before this PR is ready:

1. File-level JSDoc (line 13) — /insightsrtm_/Traceview/* is no longer the full picture; the governance endpoints are now on llmopstenant_/api/Governance/agentic/*.

2. Skip justification (lines 21–22) — "insightsrtm_ endpoints reject PAT tokens entirely" is only true for the five Traceview methods. The two governance methods now support PAT (Traces.Api).

3. Test structure (line 23) — The getGovernanceDecisions and getGovernanceSummary describe blocks are nested inside the outer describe.skip, so they never run. Now that those endpoints are on llmops and PAT-compatible, they should be moved to a non-skipped block (or the outer skip restructured so only the Traceview methods remain skipped). Leaving them skipped is now a CLAUDE.md violation.

[claude]

Review findings

Two open issues:

1. New — docs/oauth-scopes.md lines 272–273 (inline comment posted): the scope for getGovernanceDecisions() and getGovernanceSummary() reads Traces.Api Insights.RealTimeData Insights OR.Folders.Read — looks like Traces.Api was prepended to the old scope rather than replacing it. The PR description says the scope becomes Traces.Api OR.Folders.Read, matching every other llmops-backed method.

2. Prior open — integration test (from previous review, still unresolved): tests/integration/shared/observability/traces/agent.integration.test.ts — the getGovernanceDecisions and getGovernanceSummary describe blocks are still nested inside the outer describe.skip. Per CLAUDE.md, skip is only permitted when the service does not support PAT auth. These two methods now live on llmopstenant_ and accept Traces.Api tokens, so they must be moved out of the outer skip.

[ashishupadhyay88]

Thanks — both findings were based on the assumption that these are plain Traces.Api llmops endpoints. E2E + backend logs show otherwise, so here is the resolution:

1. Scope (docs/oauth-scopes.md) — the full Traces.Api Insights.RealTimeData Insights OR.Folders.Read is correct and required, not an accidental prepend. The llmops governance route is a facade that forwards to InsightsRTM; the token must satisfy both the llmops gateway (Traces.Api) and the internal InsightsRTM call (Insights.RealTimeData Insights OR.Folders.Read). A reduced Traces.Api OR.Folders.Read token 401s on the forward. PR description updated to explain this.

2. Integration test skip — kept skipped, comment corrected in aaff672. The premise that these now "accept PAT with Traces.Api" is not true: because the facade forwards to InsightsRTM (which rejects PAT), PAT still cannot reach the governance endpoints. So describe.skip remains correct per CLAUDE.md (service does not support PAT). Updated the file-level JSDoc and skip justification to reflect the llmops move while keeping the skip.

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[claude]

✅ No issues found. Checked for bugs and CLAUDE.md compliance.