fix(agentic-workload-explorer): keep ?version= across session links

- The bare `/sessions/{id}` redirect now forwards `?version=` to the
  conversation tab.
- `useExplorerHref` carries the current `?version=` into every in-explorer
  link (session rows, error and web-search links, session tabs, breadcrumbs),
  merging with existing queries and `#fragments` via `withVersion`.
- Session tab activity now matches the explorer-relative path, since tab
  hrefs may carry a query string.
- `versionQuery` moves to `paths.ts` so server redirect pages can use it.

中文：裸 `/sessions/{id}` 重定向及 explorer 内所有链接（会话列表、错误与 Web 搜索链接、
会话标签页、面包屑）现在都会保留 `?version=` 筛选；会话标签页的选中状态改为按
explorer 相对路径判断。

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: functionstackx

packages/app/src/app/(dashboard)/agentic-workload-explorer/sessions/[id]/page.tsx

@@ -1,20 +1,21 @@
 import type { Metadata } from 'next';
 import { redirect } from 'next/navigation';
 
-import { explorerHref } from '@/lib/agentic-workload-explorer/paths';
+import { explorerHref, versionQuery } from '@/lib/agentic-workload-explorer/paths';
 import { explorerSessionMetadata } from '@/lib/agentic-workload-explorer/page-meta';
 
 interface Props {
   params: Promise<{ id: string }>;
+  searchParams: Promise<Record<string, string | string[] | undefined>>;
 }
 
 export async function generateMetadata({ params }: Props): Promise<Metadata> {
   const { id } = await params;
   return explorerSessionMetadata(decodeURIComponent(id), 'conversation', 'en');
 }
 
-/** A bare session URL opens its conversation tab. */
-export default async function ExplorerSessionPage({ params }: Props) {
-  const { id } = await params;
-  redirect(explorerHref(`/sessions/${id}/conversation`, 'en'));
+/** A bare session URL opens its conversation tab, keeping the trace-version filter. */
+export default async function ExplorerSessionPage({ params, searchParams }: Props) {
+  const [{ id }, { version }] = await Promise.all([params, searchParams]);
+  redirect(explorerHref(`/sessions/${id}/conversation`, 'en') + versionQuery(version));
 }

packages/app/src/app/zh/(dashboard)/agentic-workload-explorer/sessions/[id]/page.tsx

@@ -1,20 +1,21 @@
 import type { Metadata } from 'next';
 import { redirect } from 'next/navigation';
 
-import { explorerHref } from '@/lib/agentic-workload-explorer/paths';
+import { explorerHref, versionQuery } from '@/lib/agentic-workload-explorer/paths';
 import { explorerSessionMetadata } from '@/lib/agentic-workload-explorer/page-meta';
 
 interface Props {
   params: Promise<{ id: string }>;
+  searchParams: Promise<Record<string, string | string[] | undefined>>;
 }
 
 export async function generateMetadata({ params }: Props): Promise<Metadata> {
   const { id } = await params;
   return explorerSessionMetadata(decodeURIComponent(id), 'conversation', 'zh');
 }
 
-/** A bare session URL opens its conversation tab. */
-export default async function ZhExplorerSessionPage({ params }: Props) {
-  const { id } = await params;
-  redirect(explorerHref(`/sessions/${id}/conversation`, 'zh'));
+/** A bare session URL opens its conversation tab, keeping the trace-version filter. */
+export default async function ZhExplorerSessionPage({ params, searchParams }: Props) {
+  const [{ id }, { version }] = await Promise.all([params, searchParams]);
+  redirect(explorerHref(`/sessions/${id}/conversation`, 'zh') + versionQuery(version));
 }

packages/app/src/components/agentic-workload-explorer/__tests__/errors-page-retry.test.tsx

@@ -3,6 +3,7 @@
 import { act, type AnchorHTMLAttributes, type ReactNode } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type * as NextNavigation from 'next/navigation';
 import type { ErrorData } from '@/lib/agentic-workload-explorer/api-types';
 
 const mocks = vi.hoisted(() => ({
@@ -25,6 +26,12 @@ vi.mock('next/link', () => ({
   ),
 }));
 
+// Rendered outside the App Router, so `useSearchParams` has no context.
+vi.mock('next/navigation', async (importOriginal) => ({
+  ...(await importOriginal<typeof NextNavigation>()),
+  useSearchParams: () => new URLSearchParams(),
+}));
+
 vi.mock('@/hooks/agentic-workload-explorer/use-trace-version', () => ({
   useTraceVersion: () => ({ apiParam: null }),
   appendTraceVersion: (url: string) => url,

packages/app/src/components/agentic-workload-explorer/section-nav.tsx

@@ -5,7 +5,11 @@ import Link from 'next/link';
 import { usePathname, useRouter, useSearchParams } from 'next/navigation';
 import { Suspense, useEffect, useMemo, useRef, useState } from 'react';
 
-import { explorerHref, explorerRelativePath } from '@/lib/agentic-workload-explorer/paths';
+import {
+  explorerHref,
+  explorerRelativePath,
+  versionQuery,
+} from '@/lib/agentic-workload-explorer/paths';
 import { track } from '@/lib/analytics';
 import type { Locale } from '@/lib/i18n';
 import { useLocale } from '@/lib/use-locale';
@@ -57,14 +61,6 @@ export function isActiveSection(relativePath: string | null, sectionPath: string
   return relativePath === sectionPath || relativePath.startsWith(`${sectionPath}/`);
 }
 
-/**
- * Query string carried across section links. The trace-version selection
- * lives only in `?version=`, so dropping it would reset the filter.
- */
-export function versionQuery(version: string | null): string {
-  return version === null ? '' : `?version=${encodeURIComponent(version)}`;
-}
-
 /** Number keys 1-9 jump to the first nine sections and 0 to the tenth. */
 function useSectionHotkeys(locale: Locale, query: string) {
   const router = useRouter();

packages/app/src/components/agentic-workload-explorer/views/session-detail-layout.tsx

@@ -224,7 +224,7 @@ export default function SessionLayout({ children }: { children: React.ReactNode
   }
   const { session, requests } = data;
   const { usage } = session;
-  const basePath = explorerHref(`/sessions/${id}`);
+  const sessionPath = `/sessions/${id}`;
 
   function selectReversed(next: boolean) {
     setReversed(next);
@@ -249,8 +249,12 @@ export default function SessionLayout({ children }: { children: React.ReactNode
     'radix-tree',
   ];
   const navLinks = tabKeys.map((key) => ({
-    href: `${basePath}/${key}`,
+    href: explorerHref(`${sessionPath}/${key}`),
     label: EXPLORER_SESSION_TAB_META[key][locale],
+    // Match on the explorer-relative path; `href` may carry `?version=`.
+    active:
+      relativePath === `${sessionPath}/${key}` ||
+      (key === 'conversation' && relativePath === sessionPath),
   }));
 
   return (
@@ -385,9 +389,7 @@ export default function SessionLayout({ children }: { children: React.ReactNode
           {/* Scrolls on its own on narrow screens instead of widening the page. */}
           <nav className="flex min-w-0 items-center gap-0.5 overflow-x-auto border border-border rounded-md p-0.5">
             {navLinks.map((link) => {
-              const isActive =
-                pathname === link.href ||
-                (link.href.endsWith('/conversation') && pathname === basePath);
+              const isActive = link.active;
               return (
                 <Link
                   key={link.href}

packages/app/src/hooks/agentic-workload-explorer/use-explorer-href.ts

@@ -1,12 +1,21 @@
 'use client';
 
+import { useSearchParams } from 'next/navigation';
 import { useCallback } from 'react';
 
-import { explorerHref } from '@/lib/agentic-workload-explorer/paths';
+import { explorerHref, withVersion } from '@/lib/agentic-workload-explorer/paths';
 import { useLocale } from '@/lib/use-locale';
 
-/** Locale-aware `explorerHref` bound to the current page's language. */
+/**
+ * Locale-aware `explorerHref` bound to the current page's language. Links
+ * keep the current `?version=` so the trace-version filter survives
+ * navigation inside the explorer.
+ */
 export function useExplorerHref(): (path: string) => string {
   const locale = useLocale();
-  return useCallback((path: string) => explorerHref(path, locale), [locale]);
+  const version = useSearchParams().get('version');
+  return useCallback(
+    (path: string) => withVersion(explorerHref(path, locale), version),
+    [locale, version],
+  );
 }

packages/app/src/lib/agentic-workload-explorer/page-meta.test.ts

@@ -4,11 +4,7 @@ import path from 'node:path';
 import { SITE_URL } from '@semianalysisai/inferencex-constants';
 import { describe, expect, it } from 'vitest';
 
-import {
-  ALL_SECTIONS,
-  isActiveSection,
-  versionQuery,
-} from '@/components/agentic-workload-explorer/section-nav';
+import { ALL_SECTIONS, isActiveSection } from '@/components/agentic-workload-explorer/section-nav';
 
 import {
   EXPLORER_SECTION_META,
@@ -86,10 +82,3 @@ describe('isActiveSection', () => {
     expect(isActiveSection(null, '/sessions')).toBe(false);
   });
 });
-
-describe('versionQuery', () => {
-  it('carries the trace-version selection across section links', () => {
-    expect(versionQuery(null)).toBe('');
-    expect(versionQuery('all')).toBe('?version=all');
-  });
-});

packages/app/src/lib/agentic-workload-explorer/paths.test.ts

@@ -1,6 +1,13 @@
 import { describe, expect, it } from 'vitest';
 
-import { EXPLORER_API_BASE, EXPLORER_BASE_PATH, explorerHref, explorerRelativePath } from './paths';
+import {
+  EXPLORER_API_BASE,
+  EXPLORER_BASE_PATH,
+  explorerHref,
+  explorerRelativePath,
+  versionQuery,
+  withVersion,
+} from './paths';
 
 describe('explorerHref', () => {
   it('maps the explorer root to the base path in each locale', () => {
@@ -37,3 +44,32 @@ it('keeps the page and API prefixes aligned with the route directories', () => {
   expect(EXPLORER_BASE_PATH).toBe('/agentic-workload-explorer');
   expect(EXPLORER_API_BASE).toBe('/api/v1/agentic-workload-explorer');
 });
+
+describe('versionQuery', () => {
+  it('carries the trace-version selection across explorer links', () => {
+    expect(versionQuery(null)).toBe('');
+    expect(versionQuery(undefined)).toBe('');
+    expect(versionQuery('all')).toBe('?version=all');
+    expect(versionQuery(['all', '2'])).toBe('?version=all');
+  });
+});
+
+describe('withVersion', () => {
+  it('leaves the href alone without a selection', () => {
+    expect(withVersion('/agentic-workload-explorer/sessions', null)).toBe(
+      '/agentic-workload-explorer/sessions',
+    );
+  });
+
+  it('merges into an existing query and keeps the fragment', () => {
+    expect(withVersion('/agentic-workload-explorer/sessions/a/conversation#req-1', 'all')).toBe(
+      '/agentic-workload-explorer/sessions/a/conversation?version=all#req-1',
+    );
+    expect(withVersion('/agentic-workload-explorer/sessions?sort=cost', 'all')).toBe(
+      '/agentic-workload-explorer/sessions?sort=cost&version=all',
+    );
+    expect(withVersion('/agentic-workload-explorer/sessions?version=2', 'all')).toBe(
+      '/agentic-workload-explorer/sessions?version=2',
+    );
+  });
+});

packages/app/src/lib/agentic-workload-explorer/paths.ts

@@ -26,3 +26,28 @@ export function explorerRelativePath(pathname: string): string | null {
   if (!enPath.startsWith(`${EXPLORER_BASE_PATH}/`)) return null;
   return enPath.slice(EXPLORER_BASE_PATH.length);
 }
+
+/**
+ * Query string carried across explorer links. The trace-version selection
+ * lives only in `?version=`, so dropping it would reset the filter.
+ */
+export function versionQuery(version: string | string[] | null | undefined): string {
+  const value = Array.isArray(version) ? version[0] : version;
+  return value === null || value === undefined ? '' : `?version=${encodeURIComponent(value)}`;
+}
+
+/**
+ * Add the trace-version selection to an explorer href that may already carry
+ * a query string or a `#fragment`. An explicit `version` in `href` wins.
+ */
+export function withVersion(href: string, version: string | null): string {
+  if (version === null) return href;
+  const hashAt = href.indexOf('#');
+  const hash = hashAt === -1 ? '' : href.slice(hashAt);
+  const beforeHash = hashAt === -1 ? href : href.slice(0, hashAt);
+  const queryAt = beforeHash.indexOf('?');
+  const path = queryAt === -1 ? beforeHash : beforeHash.slice(0, queryAt);
+  const params = new URLSearchParams(queryAt === -1 ? '' : beforeHash.slice(queryAt + 1));
+  if (!params.has('version')) params.set('version', version);
+  return `${path}?${params.toString()}${hash}`;
+}