Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat(noramlized-io): hook up parser trace io behind feature flag (#16775)

marliessophiefbd612a200e3
diff --git a/web/.storybook/preview.tsx b/web/.storybook/preview.tsx
index 973376d3d0..5cda953cf2 100644
--- a/web/.storybook/preview.tsx
+++ b/web/.storybook/preview.tsx
@@ -11,6 +11,7 @@ import {
type ComponentProps,
type ReactNode,
} from "react";
+import { SessionProvider } from "next-auth/react";
import { TooltipProvider } from "../src/components/ui/tooltip";
import { ThemeProvider } from "../src/features/theming/ThemeProvider";
import { MarkdownContextProvider } from "../src/features/theming/useMarkdownContext";
@@ -158,11 +159,16 @@ export default definePreview({
the JSON/IO viewers (CodeJsonViewer's JSONView calls
useMarkdownContext) work identically to production. Without it,
multi-line IOTableCell renders (rowHeight m/l) throw. */}
- <MarkdownContextProvider>
- <TooltipProvider>
- <Story />
- </TooltipProvider>
- </MarkdownContextProvider>
+ {/* SessionProvider mirrors _app.tsx: components reading feature
+ flags call useSession, which throws without a provider. A null
+ session resolves every flag to false (regular-user behavior). */}
+ <SessionProvider session={null}>
+ <MarkdownContextProvider>
+ <TooltipProvider>
+ <Story />
+ </TooltipProvider>
+ </MarkdownContextProvider>
+ </SessionProvider>
</StorybookThemeProvider>
),
],
diff --git a/web/src/components/session/SessionObservationIO.clienttest.tsx b/web/src/components/session/SessionObservationIO.clienttest.tsx
index 85ba3deda9..77c42c052e 100644
--- a/web/src/components/session/SessionObservationIO.clienttest.tsx
+++ b/web/src/components/session/SessionObservationIO.clienttest.tsx
@@ -5,6 +5,7 @@
* (trace view, raw download) instead of the full payload.
*/
import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { SessionProvider } from "next-auth/react";
const fullIOQuery = vi.fn();
const downloadJsonFile = vi.fn();
@@ -69,14 +70,19 @@ const renderComponent = (
onOpenInTraceView = vi.fn(),
) => {
render(
- <SessionObservationIO
- observation={observation}
- projectId="p1"
- sessionId="s1"
- traceId="t1"
- showCorrections={false}
- onOpenInTraceView={onOpenInTraceView}
- />,
+ // IOPreview reads the normalizedIoPreview flag via useSession; a null
+ // session resolves it to false (legacy behavior), matching production
+ // for regular users.
+ <SessionProvider session={null}>
+ <SessionObservationIO
+ observation={observation}
+ projectId="p1"
+ sessionId="s1"
+ traceId="t1"
+ showCorrections={false}
+ onOpenInTraceView={onOpenInTraceView}
+ />
+ </SessionProvider>,
);
return { onOpenInTraceView };
};
diff --git a/web/src/features/feature-flags/available-flags.ts b/web/src/features/feature-flags/available-flags.ts
index 9e81906642..1a1242badb 100644
--- a/web/src/features/feature-flags/available-flags.ts
+++ b/web/src/features/feature-flags/available-flags.ts
@@ -40,4 +40,7 @@ export const availableFlags = [
"v4BetaToggleVisible",
"observationEvals",
"experimentsV4Enabled",
+ // Internal flag (deliberately NOT in featurePreviewFlags): gates the
+ // normalized-parser formatted trace view for admins/flagged users only.
+ "normalizedIoPreview",
] as const;
diff --git a/web/src/features/feature-flags/types.ts b/web/src/features/feature-flags/types.ts
index c470a211ab..0f1da62fd3 100644
--- a/web/src/features/feature-flags/types.ts
+++ b/web/src/features/feature-flags/types.ts
@@ -2,8 +2,9 @@ import { type availableFlags } from "./available-flags";
export type Flag = (typeof availableFlags)[number];
export type Flags = {
- [key in Exclude<Flag, "modernSession">]: boolean;
+ [key in Exclude<Flag, "modernSession" | "normalizedIoPreview">]: boolean;
} & {
// Optional while older sessions and test fixtures roll across new flags.
modernSession?: boolean;
+ normalizedIoPreview?: boolean;
};
diff --git a/web/src/features/traces/components/IOPreview/IOPreview.tsx b/web/src/features/traces/components/IOPreview/IOPreview.tsx
index be6c36c6bb..5f8080cb75 100644
--- a/web/src/features/traces/components/IOPreview/IOPreview.tsx
+++ b/web/src/features/traces/components/IOPreview/IOPreview.tsx
@@ -1,5 +1,6 @@
import { useEffect } from "react";
import { type ScoreDomain, type Prisma } from "@langfuse/shared";
+import useIsFeatureEnabled from "@/src/features/feature-flags/hooks/useIsFeatureEnabled";
import { usePostHogClientCapture } from "@/src/features/posthog-analytics/usePostHogClientCapture";
import useLocalStorage from "@/src/components/useLocalStorage";
import { usePreserveRelativeScroll } from "@/src/features/traces/hooks/usePreserveRelativeScroll";
@@ -150,6 +151,11 @@ export function IOPreview({
showCorrections = true,
}: IOPreviewProps) {
const capture = usePostHogClientCapture();
+ // The normalized-parser formatted view is gated to admins and explicitly
+ // flagged users; it must never surface for regular users.
+ const showPrettyBeta = useIsFeatureEnabled("normalizedIoPreview", {
+ projectId,
+ });
const [dismissedTraceViewNotifications, setDismissedTraceViewNotifications] =
useLocalStorage<string[]>(STORAGE_KEY, []);
@@ -226,6 +232,8 @@ export function IOPreview({
selectedView={selectedView}
onViewChange={handleViewChange}
compensateScrollRef={compensateScrollRef}
+ showPrettyBeta={showPrettyBeta}
+ prettyBetaDisabled={chatMLParserResult !== undefined}
/>
)}
@@ -297,6 +305,15 @@ export function IOPreview({
) : (
<IOPreviewPretty
{...sharedProps}
+ parser={
+ // Precomputed legacy parses win inside the parser hook, so a
+ // beta-labeled view must never claim them as normalized output.
+ selectedView === "pretty-beta" &&
+ showPrettyBeta &&
+ chatMLParserResult === undefined
+ ? "normalized"
+ : "legacy"
+ }
observationName={observationName}
showMetadata={showMetadata}
contentMode={contentMode}
diff --git a/web/src/features/traces/components/IOPreview/IOPreviewPretty.tsx b/web/src/features/traces/components/IOPreview/IOPreviewPretty.tsx
index 325b0b4762..0f271ba352 100644
--- a/web/src/features/traces/components/IOPreview/IOPreviewPretty.tsx
+++ b/web/src/features/traces/components/IOPreview/IOPreviewPretty.tsx
@@ -4,10 +4,11 @@ import { PrettyJsonView } from "@/src/components/ui/PrettyJsonView";
import { type MetadataFilterActions } from "@/src/components/table/ValueCell";
import { useMarkdownRenderCharacterLimit } from "@/src/hooks/useMarkdownRenderCharacterLimit";
import { type MediaReturnType } from "@/src/features/media/validation";
+import { type ChatMLParserResult } from "../../hooks/useChatMLParser";
import {
- type ChatMLParserResult,
- useChatMLParser,
-} from "../../hooks/useChatMLParser";
+ type IOPreviewParserMode,
+ useIOPreviewParser,
+} from "../../hooks/useIOPreviewParser";
import { ChatMessageList } from "../ChatMessageList";
import { SectionToolDefinitions } from "./components/SectionToolDefinitions";
import {
@@ -112,6 +113,9 @@ export interface IOPreviewPrettyProps extends ExpansionStateProps {
showCorrections?: boolean;
contentMode?: IOPreviewContentMode;
showSystemPrompt?: boolean;
+ // Which parser produces the preview; the normalized parser is admin-only
+ // while it is being validated. Legacy remains the safe default.
+ parser?: IOPreviewParserMode;
}
/**
@@ -123,8 +127,8 @@ export interface IOPreviewPrettyProps extends ExpansionStateProps {
* - Large content safety (markdown rendering limit)
* - Accepts pre-parsed data to avoid duplicate parsing
*
- * This component performs ChatML parsing which is only needed for pretty view.
- * For JSON view, use IOPreviewJSON instead.
+ * This component selects and renders the pretty-view parser output. For JSON
+ * view, use IOPreviewJSON instead.
*/
export function IOPreviewPretty({
input,
@@ -157,6 +161,7 @@ export function IOPreviewPretty({
showCorrections = true,
contentMode = "all",
showSystemPrompt,
+ parser = "legacy",
}: IOPreviewPrettyProps) {
// Use pre-parsed data if available (from useParsedObservation hook),
// otherwise parse with size/depth limits to prevent UI freeze
@@ -184,7 +189,8 @@ export function IOPreviewPretty({
[projectId, observationId],
);
- // Parse ChatML format
+ // Parse into the shared preview contract. The normalized parser is opt-in
+ // while it is being rolled out; legacy remains the safe default.
const {
canDisplayAsChat,
allMessages,
@@ -195,7 +201,8 @@ export function IOPreviewPretty({
messageToToolCallNumbers,
toolNameToDefinitionNumber,
inputMessageCount,
- } = useChatMLParser(
+ } = useIOPreviewParser(
+ parser,
input,
output,
metadata,
diff --git a/web/src/features/traces/components/IOPreview/components/ViewModeToggle.tsx b/web/src/features/traces/components/IOPreview/components/ViewModeToggle.tsx
index 8f2e6f0aa1..2bb50f9554 100644
--- a/web/src/features/traces/components/IOPreview/components/ViewModeToggle.tsx
+++ b/web/src/features/traces/components/IOPreview/components/ViewModeToggle.tsx
@@ -1,26 +1,42 @@
import { Tabs, TabsList, TabsTrigger } from "@/src/components/ui/tabs";
+import {
+ HoverCard,
+ HoverCardContent,
+ HoverCardTrigger,
+} from "@/src/components/ui/hover-card";
import { Switch } from "@/src/components/design-system/Switch/Switch";
import { useJsonBetaToggle } from "@/src/features/traces/hooks/useJsonBetaToggle";
-export type ViewMode = "pretty" | "json" | "json-beta";
+export type ViewMode = "pretty" | "pretty-beta" | "json" | "json-beta";
export interface ViewModeToggleProps {
selectedView: ViewMode;
onViewChange: (view: ViewMode) => void;
compensateScrollRef: React.RefObject<HTMLDivElement | null>;
+ /** Admin-only normalized-parser formatted view. */
+ showPrettyBeta?: boolean;
+ /** Surface supplies a precomputed legacy parse, so the beta parser cannot
+ * apply here: the trigger renders disabled with an explanation. */
+ prettyBetaDisabled?: boolean;
}
export function ViewModeToggle({
selectedView,
onViewChange,
compensateScrollRef,
+ showPrettyBeta = false,
+ prettyBetaDisabled = false,
}: ViewModeToggleProps) {
const {
jsonBetaEnabled,
selectedViewTab,
handleViewTabChange,
handleBetaToggle,
- } = useJsonBetaToggle(selectedView, onViewChange);
+ } = useJsonBetaToggle(
+ selectedView,
+ onViewChange,
+ showPrettyBeta && !prettyBetaDisabled,
+ );
return (
<div className="flex w-full flex-row items-center justify-start gap-1.5">
@@ -31,6 +47,28 @@ export function ViewModeToggle({
onValueChange={handleViewTabChange}
>
<TabsList className="h-fit p-0.5">
+ {showPrettyBeta &&
+ (prettyBetaDisabled ? (
+ <HoverCard openDelay={200}>
+ <HoverCardTrigger asChild>
+ <TabsTrigger
+ value="pretty-beta"
+ className="h-fit px-1 text-xs"
+ disabled
+ >
+ Normalized (beta)
+ </TabsTrigger>
+ </HoverCardTrigger>
+ <HoverCardContent align="start" className="w-64 text-sm">
+ Shown with the standard parser for now — beta parsing is not
+ applied to precomputed views yet.
+ </HoverCardContent>
+ </HoverCard>
+ ) : (
+ <TabsTrigger value="pretty-beta" className="h-fit px-1 text-xs">
+ Normalized (beta)
+ </TabsTrigger>
+ ))}
<TabsTrigger value="pretty" className="h-fit px-1 text-xs">
Formatted
</TabsTrigger>
diff --git a/web/src/features/traces/components/ObservationDetailView/ConnectedObservationDetailView.tsx b/web/src/features/traces/components/ObservationDetailView/ConnectedObservationDetailView.tsx
index 088c2cbaed..df5854aadc 100644
--- a/web/src/features/traces/components/ObservationDetailView/ConnectedObservationDetailView.tsx
+++ b/web/src/features/traces/components/ObservationDetailView/ConnectedObservationDetailView.tsx
@@ -64,6 +64,7 @@ import {
} from "@/src/features/traces/fns/traceAggregation";
import { useHasProjectAccess } from "@/src/features/rbac/utils/checkProjectAccess";
import { useSession } from "next-auth/react";
+import useIsFeatureEnabled from "@/src/features/feature-flags/hooks/useIsFeatureEnabled";
import { ObservationPreview } from "./ObservationPreview";
export interface ConnectedObservationDetailViewProps {
@@ -176,15 +177,30 @@ export function ConnectedObservationDetailView({
setGlobalSelectedTab(tab);
};
+ // The normalized-parser formatted view is gated to admins and explicitly
+ // flagged users; it must never surface for regular users.
+ const showPrettyBeta = useIsFeatureEnabled("normalizedIoPreview", {
+ projectId,
+ });
+
// Map jsonViewPreference to currentView format expected by child components
const currentView = jsonViewPreference;
- const selectedViewTab = currentView === "pretty" ? "pretty" : "json";
+ // A persisted "pretty-beta" preference clamps to "pretty" when the beta
+ // tab is unavailable, so the highlighted tab matches the rendered parser.
+ const selectedViewTab =
+ currentView === "pretty-beta"
+ ? showPrettyBeta
+ ? "pretty-beta"
+ : "pretty"
+ : currentView === "pretty"
+ ? "pretty"
+ : "json";
const [isPrettyViewAvailable, setIsPrettyViewAvailable] = useState(true);
const handleViewTabChange = useCallback(
(tab: string) => {
- if (tab === "pretty") {
- setJsonViewPreference("pretty");
+ if (tab === "pretty" || tab === "pretty-beta") {
+ setJsonViewPreference(tab);
} else {
// When switching to JSON, use beta preference
setJsonViewPreference(jsonBetaEnabled ? "json-beta" : "json");
@@ -358,7 +374,9 @@ export function ConnectedObservationDetailView({
<Tabs
className="ml-auto h-fit px-2 py-0.5"
value={
- selectedTab === "log" && isLogViewVirtualized
+ selectedTab === "log" &&
+ (isLogViewVirtualized ||
+ selectedViewTab === "pretty-beta")
? "pretty"
: selectedViewTab
}
@@ -374,6 +392,16 @@ export function ConnectedObservationDetailView({
}}
>
<TabsList className="h-fit py-0.5">
+ {/* Log view never runs the normalized parser, so the
+ beta tab only renders on the preview tab. */}
+ {showPrettyBeta && selectedTab !== "log" && (
+ <TabsTrigger
+ value="pretty-beta"
+ className="h-fit px-1 text-xs"
+ >
+ Normalized (beta)
+ </TabsTrigger>
+ )}
<TabsTrigger
value="pretty"
className="h-fit px-1 text-xs"
diff --git a/web/src/features/traces/components/ObservationDetailView/ObservationPreview.tsx b/web/src/features/traces/components/ObservationDetailView/ObservationPreview.tsx
index cb5d32cf69..e176088c1a 100644
--- a/web/src/features/traces/components/ObservationDetailView/ObservationPreview.tsx
+++ b/web/src/features/traces/components/ObservationDetailView/ObservationPreview.tsx
@@ -34,12 +34,12 @@ export function ObservationPreview({
{tags && tags.length > 0 ? (
<>
<div
- className={`px-2 pt-2 text-sm font-bold ${currentView && currentView !== "pretty" ? "shrink-0" : ""}`}
+ className={`px-2 pt-2 text-sm font-bold ${currentView && currentView !== "pretty" && currentView !== "pretty-beta" ? "shrink-0" : ""}`}
>
Tags
</div>
<div
- className={`flex flex-wrap gap-x-1 gap-y-1 px-2 pb-2 ${currentView && currentView !== "pretty" ? "shrink-0" : ""}`}
+ className={`flex flex-wrap gap-x-1 gap-y-1 px-2 pb-2 ${currentView && currentView !== "pretty" && currentView !== "pretty-beta" ? "shrink-0" : ""}`}
>
<TagList selectedTags={tags} isLoading={false} />
</div>
diff --git a/web/src/features/traces/components/ToolCallInvocationsView.tsx b/web/src/features/traces/components/ToolCallInvocationsView.tsx
index 9dfc7e23bf..5bfde03f1f 100644
--- a/web/src/features/traces/components/ToolCallInvocationsView.tsx
+++ b/web/src/features/traces/components/ToolCallInvocationsView.tsx
@@ -11,12 +11,37 @@ interface ToolCallInvocationsViewProps {
className?: string;
}
+/**
+ * Projection-only extras on tool-call entries. The normalized-parser
+ * projection (`toIOPreview`) builds messages without schema validation and
+ * supplies decoded `arguments` plus a paired `response`; the wire schema
+ * (`ToolCallSchema`) deliberately stays untouched so legacy validation is
+ * unchanged. Legacy messages never carry `response`.
+ */
+type ToolCallEntry = NonNullable<
+ z.infer<typeof ChatMlMessageSchema>["tool_calls"]
+>[number] & {
+ arguments: unknown;
+ response?: { output: unknown; isError?: boolean } | null;
+};
+
+/** Tool outputs are frequently JSON serialized as a string; show the
+ * structure when it parses, the raw string otherwise. */
+function parseIfJsonString(value: unknown): unknown {
+ if (typeof value !== "string") return value;
+ try {
+ return JSON.parse(value);
+ } catch {
+ return value;
+ }
+}
+
export function ToolCallInvocationsView({
message,
toolCallNumbers,
className,
}: ToolCallInvocationsViewProps) {
- const toolCalls = message.tool_calls;
+ const toolCalls = message.tool_calls as ToolCallEntry[] | undefined;
if (!toolCalls || !Array.isArray(toolCalls) || toolCalls.length === 0) {
return null;
@@ -80,6 +105,31 @@ export function ToolCallInvocationsView({
codeClassName="text-xs"
/>
</div>
+
+ {/* Response view: paired tool result. Only the normalized-parser
+ projection sets `response`, so this section is beta-only by
+ data presence — legacy messages never carry the field. */}
+ {toolCall.response !== undefined && (
+ <div className="py-2 [&_.io-message-content]:px-0">
+ <div className="text-muted-foreground mb-1.5 text-xs font-bold">
+ Response
+ {toolCall.response?.isError && (
+ <span className="text-dark-red ml-1">(error)</span>
+ )}
+ </div>
+ {toolCall.response === null ? (
+ <div className="text-muted-foreground text-xs">
+ No response
+ </div>
+ ) : (
+ <PrettyJsonView
+ json={parseIfJsonString(toolCall.response.output)}
+ currentView="pretty"
+ codeClassName="text-xs"
+ />
+ )}
+ </div>
+ )}
</div>
);
})}
diff --git a/web/src/features/traces/components/TraceDetailView/TraceDetailView.tsx b/web/src/features/traces/components/TraceDetailView/TraceDetailView.tsx
index afd8a9dbf4..8bbcaa0412 100644
--- a/web/src/features/traces/components/TraceDetailView/TraceDetailView.tsx
+++ b/web/src/features/traces/components/TraceDetailView/TraceDetailView.tsx
@@ -43,6 +43,7 @@ import { useIsAuthenticatedAndProjectMember } from "@/src/features/auth/hooks";
import { useCommentedPaths } from "@/src/features/comments/hooks/useCommentedPaths";
import { useHasProjectAccess } from "@/src/features/rbac/utils/checkProjectAccess";
import { useSession } from "next-auth/react";
+import useIsFeatureEnabled from "@/src/features/feature-flags/hooks/useIsFeatureEnabled";
// Extracted components
import { TraceDetailViewHeader } from "./components/TraceDetailViewHeader";
@@ -100,16 +101,33 @@ export function TraceDetailView({
isAnnotationMode,
} = useViewPreferences();
+ // The normalized-parser formatted view is gated to admins and explicitly
+ // flagged users; it must never surface for regular users.
+ const showPrettyBeta = useIsFeatureEnabled("normalizedIoPreview", {
+ projectId,
+ });
+
// Map jsonViewPreference to currentView format expected by child components
const currentView = jsonViewPreference;
+ // Both formatted variants share the pretty layout; JSON views differ.
+ const isPrettyLikeView =
+ currentView === "pretty" || currentView === "pretty-beta";
+ // A persisted "pretty-beta" preference clamps to "pretty" when the beta
+ // tab is unavailable, so the highlighted tab matches the rendered parser.
const selectedViewTab =
- jsonViewPreference === "pretty" ? "pretty" : ("json" as const);
+ jsonViewPreference === "pretty-beta"
+ ? showPrettyBeta
+ ? "pretty-beta"
+ : "pretty"
+ : jsonViewPreference === "pretty"
+ ? "pretty"
+ : ("json" as const);
const handleViewTabChange = useCallback(
(tab: string) => {
- if (tab === "pretty") {
- setJsonViewPreference("pretty");
+ if (tab === "pretty" || tab === "pretty-beta") {
+ setJsonViewPreference(tab);
} else {
setJsonViewPreference(jsonBetaEnabled ? "json-beta" : "json");
}
@@ -268,7 +286,9 @@ export function TraceDetailView({
<Tabs
className="ml-auto h-fit px-2 py-0.5"
value={
- selectedTab === "log" && isLogViewVirtualized
+ selectedTab === "log" &&
+ (isLogViewVirtualized ||
+ selectedViewTab === "pretty-beta")
? "pretty"
: selectedViewTab
}
@@ -285,6 +305,16 @@ export function TraceDetailView({
}}
>
<TabsList className="h-fit py-0.5">
+ {/* Log view never runs the normalized parser, so the
+ beta tab only renders on the preview tab. */}
+ {showPrettyBeta && selectedTab !== "log" && (
+ <TabsTrigger
+ value="pretty-beta"
+ className="h-fit px-1 text-xs"
+ >
+ Normalized (beta)
+ </TabsTrigger>
+ )}
<TabsTrigger
value="pretty"
className="h-fit px-1 text-xs"
@@ -364,12 +394,12 @@ export function TraceDetailView({
{trace.tags.length > 0 && (
<>
<div
- className={`px-2 pt-2 text-sm font-bold ${currentView !== "pretty" ? "shrink-0" : ""}`}
+ className={`px-2 pt-2 text-sm font-bold ${!isPrettyLikeView ? "shrink-0" : ""}`}
>
Tags
</div>
<div
- className={`flex flex-wrap gap-x-1 gap-y-1 px-2 pb-2 ${currentView !== "pretty" ? "shrink-0" : ""}`}
+ className={`flex flex-wrap gap-x-1 gap-y-1 px-2 pb-2 ${!isPrettyLikeView ? "shrink-0" : ""}`}
>
<TagList selectedTags={trace.tags} isLoading={false} />
</div>
diff --git a/web/src/features/traces/components/TraceLogView/LogViewExpandedContent.tsx b/web/src/features/traces/components/TraceLogView/LogViewExpandedContent.tsx
index 8b2600818d..a6e7640f53 100644
--- a/web/src/features/traces/components/TraceLogView/LogViewExpandedContent.tsx
+++ b/web/src/features/traces/components/TraceLogView/LogViewExpandedContent.tsx
@@ -15,7 +15,7 @@ export interface LogViewExpandedContentProps {
node: TreeNode;
traceId: string;
projectId: string;
- currentView?: "pretty" | "json" | "json-beta";
+ currentView?: "pretty" | "pretty-beta" | "json" | "json-beta";
/** Optional external expansion state for JSON tree (non-virtualized mode) */
externalExpansionState?: Record<string, boolean> | boolean;
/** Callback when expansion state changes (non-virtualized mode) */
@@ -83,8 +83,12 @@ export const LogViewExpandedContent = memo(function LogViewExpandedContent({
{jsonData && !isLoading && (
<PrettyJsonView
json={jsonData}
- // Map "json-beta" to "pretty" for PrettyJsonView since it only supports "pretty" | "json"
- currentView={currentView === "json-beta" ? "pretty" : currentView}
+ // Map beta modes to "pretty" for PrettyJsonView since it only supports "pretty" | "json"
+ currentView={
+ currentView === "json-beta" || currentView === "pretty-beta"
+ ? "pretty"
+ : currentView
+ }
isLoading={false}
showNullValues={false}
stickyTopLevelKey={false}
diff --git a/web/src/features/traces/components/TraceLogView/LogViewToolbar.tsx b/web/src/features/traces/components/TraceLogView/LogViewToolbar.tsx
index 0832b348ae..62151d69ae 100644
--- a/web/src/features/traces/components/TraceLogView/LogViewToolbar.tsx
+++ b/web/src/features/traces/components/TraceLogView/LogViewToolbar.tsx
@@ -55,8 +55,8 @@ export interface LogViewToolbarProps {
onCopyJson?: () => void;
/** Callback to download JSON */
onDownloadJson?: () => void;
- /** Current view type (pretty/json/json-beta) */
- currentView?: "pretty" | "json" | "json-beta";
+ /** Current view type (pretty/pretty-beta/json/json-beta) */
+ currentView?: "pretty" | "pretty-beta" | "json" | "json-beta";
/** Whether indent visualization is enabled */
indentEnabled?: boolean;
/** Whether indent toggle is disabled (tree too deep) */
diff --git a/web/src/features/traces/components/TraceLogView/TraceLogView.tsx b/web/src/features/traces/components/TraceLogView/TraceLogView.tsx
index 759682005e..f46ae1cc85 100644
--- a/web/src/features/traces/components/TraceLogView/TraceLogView.tsx
+++ b/web/src/features/traces/components/TraceLogView/TraceLogView.tsx
@@ -54,7 +54,7 @@ import { flattenTreeOrder } from "@/src/features/traces/components/TraceLogView/
export interface TraceLogViewProps {
traceId: string;
projectId: string;
- currentView?: "pretty" | "json" | "json-beta";
+ currentView?: "pretty" | "pretty-beta" | "json" | "json-beta";
}
// Import configuration constants
@@ -315,7 +315,9 @@ export const TraceLogView = ({
{/* Table view mode - render as expandable table */}
{/* "json-beta" uses table mode since advanced I/O viewer works in expandable rows */}
{flatItems.length > 0 &&
- (currentView === "pretty" || currentView === "json-beta") && (
+ (currentView === "pretty" ||
+ currentView === "pretty-beta" ||
+ currentView === "json-beta") && (
<JSONTableView
items={flatItems}
columns={columns}
diff --git a/web/src/features/traces/contexts/ViewPreferencesContext.tsx b/web/src/features/traces/contexts/ViewPreferencesContext.tsx
index a1dd5dbe6a..4852f6ae04 100644
--- a/web/src/features/traces/contexts/ViewPreferencesContext.tsx
+++ b/web/src/features/traces/contexts/ViewPreferencesContext.tsx
@@ -26,8 +26,13 @@ export type LogViewMode = "chronological" | "tree-order";
/** Log view tree visualization style (only applies in tree-order mode) */
export type LogViewTreeStyle = "flat" | "indented";
-/** JSON view preference (formatted/pretty vs raw JSON vs advanced JSON beta) */
-export type JsonViewPreference = "pretty" | "json" | "json-beta";
+/** JSON view preference (formatted/pretty vs raw JSON vs advanced JSON beta).
+ * "pretty-beta" is the admin-only normalized-parser formatted view. */
+export type JsonViewPreference =
+ | "pretty"
+ | "pretty-beta"
+ | "json"
+ | "json-beta";
/** Context in which trace is rendered - affects feature availability */
type TraceRenderContext = "fullscreen" | "peek" | "annotation";
diff --git a/web/src/features/traces/hooks/useChatMLParser.clienttest.ts b/web/src/features/traces/hooks/useChatMLParser.clienttest.ts
index f05064c755..eea254e90a 100644
--- a/web/src/features/traces/hooks/useChatMLParser.clienttest.ts
+++ b/web/src/features/traces/hooks/useChatMLParser.clienttest.ts
@@ -1,163 +1,178 @@
import { renderHook } from "@testing-library/react";
-import { type ChatMLParserResult, useChatMLParser } from "./useChatMLParser";
+import { normalizeSpanIO } from "@langfuse/shared/src/utils/normalized-io";
+import { toIOPreview } from "../parsers/toIOPreview";
+import {
+ parseChatML,
+ type ChatMLParserResult,
+ useChatMLParser,
+} from "./useChatMLParser";
+
+const parserImplementations = [
+ {
+ name: "legacy",
+ parse: (input: unknown, output: unknown) =>
+ parseChatML(input, output, undefined, undefined),
+ // Legacy passes arguments through as the wire carried them.
+ expectedArguments: (raw: string): unknown => raw,
+ },
+ {
+ name: "normalized",
+ parse: (input: unknown, output: unknown) =>
+ toIOPreview(
+ normalizeSpanIO({ input, output, metadata: undefined }),
+ input,
+ ),
+ // The normalized parser canonicalizes: JSON-string arguments are decoded
+ // once, so consumers always receive the parsed value.
+ expectedArguments: (raw: string): unknown => JSON.parse(raw),
+ },
+] as const;
describe("useChatMLParser", () => {
- it("groups output-side tool call arguments by tool name", () => {
- const input = {
- messages: [
+ it.each(parserImplementations)(
+ "$name parser groups output-side tool call arguments by tool name",
+ ({ parse, expectedArguments }) => {
+ const input = {
+ messages: [
+ {
+ role: "system",
+ content: "Use tools when needed.",
+ tools: [
+ {
+ name: "grep",
+ description: "Search files",
+ parameters: { type: "object" },
+ },
+ {
+ name: "write_file",
+ description: "Write a file",
+ parameters: { type: "object" },
+ },
+ ],
+ },
+ {
+ role: "assistant",
+ tool_calls: [
+ {
+ id: "historical-call",
+ name: "grep",
+ arguments: '{"query":"old"}',
+ },
+ ],
+ },
+ ],
+ };
+
+ const output = [
{
- role: "system",
- content: "Use tools when needed.",
- tools: [
+ role: "assistant",
+ tool_calls: [
{
+ id: "call-grep-1",
name: "grep",
- description: "Search files",
- parameters: { type: "object" },
+ arguments: '{"query":"first"}',
},
{
+ id: "call-write-1",
name: "write_file",
- description: "Write a file",
- parameters: { type: "object" },
+ arguments: '{"path":"todos.md"}',
},
- ],
- },
- {
- role: "assistant",
- tool_calls: [
{
- id: "historical-call",
+ id: "call-grep-2",
name: "grep",
- arguments: '{"query":"old"}',
+ arguments: '{"query":"second"}',
},
],
},
- ],
- };
+ ];
- const output = [
- {
- role: "assistant",
- tool_calls: [
+ const result = parse(input, output);
+
+ expect(result.toolCallCounts.get("grep")).toBe(2);
+ expect(result.toolCallCounts.get("write_file")).toBe(1);
+
+ expect(result.toolCallsByName.get("grep")).toEqual([
+ {
+ id: "call-grep-1",
+ name: "grep",
+ arguments: expectedArguments('{"query":"first"}'),
+ invocationNumber: 1,
+ },
+ {
+ id: "call-grep-2",
+ name: "grep",
+ arguments: expectedArguments('{"query":"second"}'),
+ invocationNumber: 3,
+ },
+ ]);
+ expect(result.toolCallsByName.get("write_file")).toEqual([
+ {
+ id: "call-write-1",
+ name: "write_file",
+ arguments: expectedArguments('{"path":"todos.md"}'),
+ invocationNumber: 2,
+ },
+ ]);
+ },
+ );
+
+ it.each(parserImplementations)(
+ "$name parser extracts args and input from raw passthrough tool calls",
+ ({ parse }) => {
+ const input = {
+ messages: [
{
- id: "call-grep-1",
- name: "grep",
- arguments: '{"query":"first"}',
+ role: "system",
+ content: "Use tools when needed.",
+ tools: [
+ {
+ name: "search",
+ parameters: { type: "object" },
+ },
+ {
+ name: "lookup",
+ parameters: { type: "object" },
+ },
+ ],
},
+ ],
+ };
+
+ const output = {
+ tool_calls: [
{
- id: "call-write-1",
- name: "write_file",
- arguments: '{"path":"todos.md"}',
+ id: "call-search",
+ toolName: "search",
+ input: { query: "docs" },
},
{
- id: "call-grep-2",
- name: "grep",
- arguments: '{"query":"second"}',
+ id: "call-lookup",
+ toolName: "lookup",
+ args: { id: "trace-1" },
},
],
- },
- ];
-
- const { result } = renderHook(() =>
- useChatMLParser(
- undefined,
- undefined,
- undefined,
- undefined,
- input,
- output,
- ),
- );
+ };
- expect(result.current.toolCallCounts.get("grep")).toBe(2);
- expect(result.current.toolCallCounts.get("write_file")).toBe(1);
-
- expect(result.current.toolCallsByName.get("grep")).toEqual([
- {
- id: "call-grep-1",
- name: "grep",
- arguments: '{"query":"first"}',
- invocationNumber: 1,
- },
- {
- id: "call-grep-2",
- name: "grep",
- arguments: '{"query":"second"}',
- invocationNumber: 3,
- },
- ]);
- expect(result.current.toolCallsByName.get("write_file")).toEqual([
- {
- id: "call-write-1",
- name: "write_file",
- arguments: '{"path":"todos.md"}',
- invocationNumber: 2,
- },
- ]);
- });
-
- it("extracts args and input from raw passthrough tool calls", () => {
- const input = {
- messages: [
- {
- role: "system",
- content: "Use tools when needed.",
- tools: [
- {
- name: "search",
- parameters: { type: "object" },
- },
- {
- name: "lookup",
- parameters: { type: "object" },
- },
- ],
- },
- ],
- };
+ const result = parse(input, output);
- const output = {
- tool_calls: [
+ expect(result.toolCallsByName.get("search")).toEqual([
{
id: "call-search",
- toolName: "search",
- input: { query: "docs" },
+ name: "search",
+ arguments: { query: "docs" },
+ invocationNumber: 1,
},
+ ]);
+ expect(result.toolCallsByName.get("lookup")).toEqual([
{
id: "call-lookup",
- toolName: "lookup",
- args: { id: "trace-1" },
+ name: "lookup",
+ arguments: { id: "trace-1" },
+ invocationNumber: 2,
},
- ],
- };
-
- const { result } = renderHook(() =>
- useChatMLParser(
- undefined,
- undefined,
- undefined,
- undefined,
- input,
- output,
- ),
- );
-
- expect(result.current.toolCallsByName.get("search")).toEqual([
- {
- id: "call-search",
- name: "search",
- arguments: { query: "docs" },
- invocationNumber: 1,
- },
- ]);
- expect(result.current.toolCallsByName.get("lookup")).toEqual([
- {
- id: "call-lookup",
- name: "lookup",
- arguments: { id: "trace-1" },
- invocationNumber: 2,
- },
- ]);
- });
+ ]);
+ },
+ );
it("reuses an already computed parser result", () => {
const preparedResult: ChatMLParserResult = {
diff --git a/web/src/features/traces/hooks/useChatMLParser.ts b/web/src/features/traces/hooks/useChatMLParser.ts
index e0bdbcd8ac..6858953aab 100644
--- a/web/src/features/traces/hooks/useChatMLParser.ts
+++ b/web/src/features/traces/hooks/useChatMLParser.ts
@@ -11,13 +11,14 @@ import {
import type { ChatMlMessageSchema } from "@/src/components/schemas/ChatMlSchema";
// ChatML message type from schema
-type ChatMlMessage = z.infer<typeof ChatMlMessageSchema>;
+export type ChatMlMessage = z.infer<typeof ChatMlMessageSchema>;
// Tool definition extracted from messages
interface ToolDefinition {
name: string;
description?: string;
parameters?: Record<string, unknown>;
+ type?: string;
}
export interface ToolCallInvocation {
@@ -27,6 +28,14 @@ export interface ToolCallInvocation {
invocationNumber: number;
}
+export interface ToolCallBookkeeping {
+ allTools: ToolDefinition[];
+ toolCallCounts: Map<string, number>;
+ toolCallsByName: Map<string, ToolCallInvocation[]>;
+ messageToToolCallNumbers: Map<number, number[]>;
+ toolNameToDefinitionNumber: Map<string, number>;
+}
+
// Result from ChatML parsing hook
export interface ChatMLParserResult {
canDisplayAsChat: boolean;
@@ -88,18 +97,11 @@ function getToolCallArguments(toolCall: unknown): unknown {
* result has any conversation representation without relying on observation
* types.
*/
-function parseChatML(
- parsedInput: unknown,
- parsedOutput: unknown,
- parsedMetadata: unknown,
- observationName: string | undefined,
-): ChatMLParserResult {
- const ctx = { metadata: parsedMetadata, observationName };
- const inResult = normalizeInput(parsedInput, ctx);
- const outResult = normalizeOutput(parsedOutput, ctx);
- const outputClean = cleanLegacyOutput(parsedOutput, parsedOutput);
- const messages = combineInputOutputMessages(inResult, outResult, outputClean);
-
+export function computeToolCallBookkeeping(
+ messages: ChatMlMessage[],
+ inputMessageCount: number,
+ additionalTools: ToolDefinition[] = [],
+): ToolCallBookkeeping {
const toolsMap = new Map<string, ToolDefinition>();
for (const message of messages) {
if (message.tools && Array.isArray(message.tools)) {
@@ -110,8 +112,12 @@ function parseChatML(
}
}
}
+ for (const tool of additionalTools) {
+ if (!toolsMap.has(tool.name)) {
+ toolsMap.set(tool.name, tool);
+ }
+ }
- const inputMessageCount = inResult.success ? inResult.data.length : 0;
let toolCallCounter = 0;
const messageToToolCallNumbers = new Map<number, number[]>();
const toolCallCounts = new Map<string, number>();
@@ -167,15 +173,44 @@ function parseChatML(
});
return {
- canDisplayAsChat:
- (inResult.success || outResult.success) && messages.length > 0,
- allMessages: messages as ChatMlMessage[],
- additionalInput: extractAdditionalInput(parsedInput),
allTools: sortedTools,
toolCallCounts,
toolCallsByName,
messageToToolCallNumbers,
toolNameToDefinitionNumber,
+ };
+}
+
+/**
+ * Parse already-decoded I/O into the same ChatML representation used by the
+ * pretty preview. Kept pure so parent surfaces can decide whether a filtered
+ * result has any conversation representation without relying on observation
+ * types.
+ */
+export function parseChatML(
+ parsedInput: unknown,
+ parsedOutput: unknown,
+ parsedMetadata: unknown,
+ observationName: string | undefined,
+): ChatMLParserResult {
+ const ctx = { metadata: parsedMetadata, observationName };
+ const inResult = normalizeInput(parsedInput, ctx);
+ const outResult = normalizeOutput(parsedOutput, ctx);
+ const outputClean = cleanLegacyOutput(parsedOutput, parsedOutput);
+ const messages = combineInputOutputMessages(inResult, outResult, outputClean);
+
+ const inputMessageCount = inResult.success ? inResult.data.length : 0;
+ const toolBookkeeping = computeToolCallBookkeeping(
+ messages,
+ inputMessageCount,
+ );
+
+ return {
+ canDisplayAsChat:
+ (inResult.success || outResult.success) && messages.length > 0,
+ allMessages: messages as ChatMlMessage[],
+ additionalInput: extractAdditionalInput(parsedInput),
+ ...toolBookkeeping,
inputMessageCount,
};
}
diff --git a/web/src/features/traces/hooks/useIOPreviewParser.ts b/web/src/features/traces/hooks/useIOPreviewParser.ts
new file mode 100644
index 0000000000..d27007078d
--- /dev/null
+++ b/web/src/features/traces/hooks/useIOPreviewParser.ts
@@ -0,0 +1,72 @@
+import { useMemo } from "react";
+import { type Prisma, deepParseJson } from "@langfuse/shared";
+import { normalizeSpanIO } from "@langfuse/shared/src/utils/normalized-io";
+import { toIOPreview } from "../parsers/toIOPreview";
+import { parseChatML, type ChatMLParserResult } from "./useChatMLParser";
+
+export type IOPreviewParserMode = "legacy" | "normalized";
+
+/**
+ * Selects the parser used by the pretty I/O preview.
+ *
+ * Both parsers return the same ChatMLParserResult, so the rendering tree does
+ * not need to know which representation produced it. A normalized parse is
+ * deliberately best-effort: malformed or unsupported data falls back to the
+ * established parser for this observation.
+ */
+export function useIOPreviewParser(
+ parser: IOPreviewParserMode,
+ input: Prisma.JsonValue | undefined,
+ output: Prisma.JsonValue | undefined,
+ metadata: Prisma.JsonValue | undefined,
+ observationName: string | undefined,
+ preParsedInput?: unknown,
+ preParsedOutput?: unknown,
+ preParsedMetadata?: unknown,
+ preParsedResult?: ChatMLParserResult,
+): ChatMLParserResult {
+ const parsedInput = preParsedResult
+ ? undefined
+ : preParsedInput !== undefined
+ ? preParsedInput
+ : deepParseJson(input, { maxSize: 300_000, maxDepth: 25 });
+ const parsedOutput = preParsedResult
+ ? undefined
+ : preParsedOutput !== undefined
+ ? preParsedOutput
+ : deepParseJson(output, { maxSize: 300_000, maxDepth: 25 });
+ const parsedMetadata = preParsedResult
+ ? undefined
+ : preParsedMetadata !== undefined
+ ? preParsedMetadata
+ : deepParseJson(metadata, { maxSize: 100_000, maxDepth: 25 });
+
+ return useMemo(() => {
+ // Precomputed results win regardless of parser mode; surfaces that supply
+ // one disable the normalized-beta tab (see IOPreview) so labels stay honest.
+ if (preParsedResult) return preParsedResult;
+
+ const parseLegacy = () =>
+ parseChatML(parsedInput, parsedOutput, parsedMetadata, observationName);
+
+ if (parser === "legacy") return parseLegacy();
+
+ try {
+ const normalized = normalizeSpanIO({
+ input: parsedInput,
+ output: parsedOutput,
+ metadata: parsedMetadata,
+ });
+ return toIOPreview(normalized, parsedInput);
+ } catch {
+ return parseLegacy();
+ }
+ }, [
+ parser,
+ preParsedResult,
+ parsedInput,
+ parsedOutput,
+ parsedMetadata,
+ observationName,
+ ]);
+}
diff --git a/web/src/features/traces/hooks/useJsonBetaToggle.ts b/web/src/features/traces/hooks/useJsonBetaToggle.ts
index c2dbc823e3..c4cff7b9b2 100644
--- a/web/src/features/traces/hooks/useJsonBetaToggle.ts
+++ b/web/src/features/traces/hooks/useJsonBetaToggle.ts
@@ -1,6 +1,6 @@
import useLocalStorage from "@/src/components/useLocalStorage";
-type ViewMode = "pretty" | "json" | "json-beta";
+type ViewMode = "pretty" | "pretty-beta" | "json" | "json-beta";
/**
* Hook for managing JSON Beta toggle state alongside view preference.
@@ -13,6 +13,10 @@ type ViewMode = "pretty" | "json" | "json-beta";
export function useJsonBetaToggle(
currentView: ViewMode,
setCurrentView: (view: ViewMode) => void,
+ /** Whether the pretty-beta tab is selectable here. A persisted
+ * "pretty-beta" preference clamps to "pretty" when it is not, so the
+ * highlighted tab always matches the parser that produced the content. */
+ prettyBetaAvailable = false,
) {
// Migration: default to true if user had json-beta selected previously
// TODO: Remove migration logic after 2025-01-26 (2 weeks) when user settings are migrated
@@ -22,13 +26,19 @@ export function useJsonBetaToggle(
localStorage.getItem("jsonViewPreference") === '"json-beta"',
);
- // Derive UI tab selection (2 tabs: pretty or json)
+ // Derive UI tab selection (pretty, flag-gated pretty-beta, or json)
const selectedViewTab =
- currentView === "pretty" ? ("pretty" as const) : ("json" as const);
+ currentView === "pretty-beta"
+ ? prettyBetaAvailable
+ ? ("pretty-beta" as const)
+ : ("pretty" as const)
+ : currentView === "pretty"
+ ? ("pretty" as const)
+ : ("json" as const);
const handleViewTabChange = (tab: string) => {
- if (tab === "pretty") {
- setCurrentView("pretty");
+ if (tab === "pretty" || tab === "pretty-beta") {
+ setCurrentView(tab);
} else {
// When switching to JSON, use beta preference
setCurrentView(jsonBetaEnabled ? "json-beta" : "json");
diff --git a/web/src/features/traces/parsers/toIOPreview.clienttest.ts b/web/src/features/traces/parsers/toIOPreview.clienttest.ts
new file mode 100644
index 0000000000..8e515e8cd1
--- /dev/null
+++ b/web/src/features/traces/parsers/toIOPreview.clienttest.ts
@@ -0,0 +1,168 @@
+import { describe, expect, it } from "vitest";
+import type { NormalizedIO } from "@langfuse/shared/src/utils/normalized-io";
+import { toIOPreview } from "./toIOPreview";
+
+const emptySpan = { input: undefined, output: undefined, metadata: undefined };
+
+describe("toIOPreview", () => {
+ it("keeps media reference tokens in the renderer-compatible shape", () => {
+ const mediaReference =
+ "@@@langfuseMedia:type=image/png|id=file-1|source=bytes@@@";
+ const io: NormalizedIO = {
+ span: emptySpan,
+ toolDefinitions: [],
+ messages: [
+ {
+ role: "user",
+ source: "input",
+ parts: [
+ { type: "text", text: "Look at this" },
+ {
+ type: "file",
+ mediaType: "image/png",
+ content: { kind: "reference", id: "file-1" },
+ providerMetadata: { source: "bytes" },
+ },
+ ],
+ },
+ ],
+ };
+
+ expect(toIOPreview(io, {}).allMessages[0]?.content).toEqual([
+ { type: "text", text: "Look at this" },
+ { type: "image_url", image_url: { url: mediaReference } },
+ ]);
+ });
+
+ it("pairs a tool result into its call entry instead of a standalone message", () => {
+ const io: NormalizedIO = {
+ span: emptySpan,
+ toolDefinitions: [
+ {
+ name: "search",
+ inputSchema: { type: "object" },
+ },
+ ],
+ messages: [
+ {
+ role: "assistant",
+ source: "output",
+ parts: [
+ {
+ type: "reasoning",
+ content: { kind: "text", text: "I should search first." },
+ },
+ {
+ type: "tool-call",
+ toolCallId: "call-1",
+ toolName: "search",
+ input: { query: "docs" },
+ },
+ {
+ type: "tool-result",
+ toolCallId: "call-1",
+ toolName: "search",
+ output: { matches: 1 },
+ },
+ ],
+ },
+ ],
+ };
+
+ const result = toIOPreview(io, {});
+
+ expect(result.allMessages).toEqual([
+ {
+ role: "assistant",
+ thinking: [{ type: "thinking", content: "I should search first." }],
+ tool_calls: [
+ {
+ id: "call-1",
+ name: "search",
+ arguments: { query: "docs" },
+ // The paired result renders inside the call card; no standalone
+ // tool message is emitted for it.
+ response: { output: { matches: 1 } },
+ },
+ ],
+ },
+ ]);
+ expect(result.inputMessageCount).toBe(0);
+ expect(result.toolCallCounts.get("search")).toBe(1);
+ expect(result.toolNameToDefinitionNumber.get("search")).toBe(1);
+ });
+
+ it("keeps unmatched tool results standalone and unanswered calls at null", () => {
+ const io: NormalizedIO = {
+ span: emptySpan,
+ toolDefinitions: [],
+ messages: [
+ {
+ role: "assistant",
+ source: "output",
+ parts: [
+ {
+ type: "tool-call",
+ toolCallId: "call-a",
+ toolName: "search",
+ input: { query: "a" },
+ },
+ {
+ type: "tool-call",
+ toolCallId: "call-b",
+ toolName: "search",
+ input: { query: "b" },
+ },
+ ],
+ },
+ {
+ role: "tool",
+ source: "output",
+ parts: [
+ {
+ type: "tool-result",
+ toolCallId: "call-a",
+ output: "boom",
+ isError: true,
+ },
+ {
+ type: "tool-result",
+ toolCallId: "call-unknown",
+ output: "orphaned",
+ },
+ ],
+ },
+ ],
+ };
+
+ const result = toIOPreview(io, {});
+
+ expect(result.allMessages).toEqual([
+ {
+ role: "assistant",
+ tool_calls: [
+ {
+ id: "call-a",
+ name: "search",
+ arguments: { query: "a" },
+ response: { output: "boom", isError: true },
+ },
+ {
+ id: "call-b",
+ name: "search",
+ arguments: { query: "b" },
+ // Unanswered call: explicit null renders as "No response".
+ response: null,
+ },
+ ],
+ },
+ {
+ // Result without a matching call stays a standalone tool message so
+ // nothing is dropped.
+ role: "tool",
+ tool_call_id: "call-unknown",
+ content: "orphaned",
+ },
+ ]);
+ });
+});
diff --git a/web/src/features/traces/parsers/toIOPreview.ts b/web/src/features/traces/parsers/toIOPreview.ts
new file mode 100644
index 0000000000..62d68f91a1
--- /dev/null
+++ b/web/src/features/traces/parsers/toIOPreview.ts
@@ -0,0 +1,299 @@
+import type {
+ FilePart,
+ JsonValue,
+ NormalizedIO,
+ NormalizedMessage,
+ NormalizedMessagePart,
+ ToolDefinition as NormalizedToolDefinition,
+} from "@langfuse/shared/src/utils/normalized-io";
+import { extractAdditionalInput } from "@/src/utils/chatml";
+import {
+ computeToolCallBookkeeping,
+ type ChatMlMessage,
+ type ChatMLParserResult,
+} from "../hooks/useChatMLParser";
+
+const MEDIA_REFERENCE_PREFIX = "@@@langfuseMedia:";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return value !== null && typeof value === "object";
+}
+
+function toMediaReference(file: FilePart): string | undefined {
+ if (file.content.kind !== "reference") return undefined;
+
+ const source = file.providerMetadata?.source;
+ const mediaType = file.mediaType;
+ if (typeof source !== "string" || !mediaType) return undefined;
+
+ return `${MEDIA_REFERENCE_PREFIX}type=${mediaType}|id=${file.content.id}|source=${source}@@@`;
+}
+
+function toImageContentPart(file: FilePart): Record<string, unknown> | string {
+ const reference = toMediaReference(file);
+ if (reference) {
+ return {
+ type: "image_url",
+ image_url: { url: reference },
+ };
+ }
+
+ if (file.content.kind === "url") {
+ return {
+ type: "image_url",
+ image_url: { url: file.content.url },
+ };
+ }
+
+ if (file.content.kind === "reference") {
+ return file.content.id;
+ }
+
+ const data = file.content.data.startsWith("data:")
+ ? file.content.data
+ : `data:${file.mediaType ?? "image/*"};base64,${file.content.data}`;
+ return {
+ type: "image_url",
+ image_url: { url: data },
+ };
+}
+
+function toToolDefinition(definition: NormalizedToolDefinition): {
+ name: string;
+ description?: string;
+ parameters?: Record<string, unknown>;
+ type?: string;
+} {
+ const parameters = isRecord(definition.inputSchema)
+ ? definition.inputSchema
+ : undefined;
+
+ return {
+ name: definition.name,
+ ...(definition.description ? { description: definition.description } : {}),
+ ...(parameters ? { parameters } : {}),
+ ...(definition.type ? { type: definition.type } : {}),
+ };
+}
+
+type ToolCallResponse = { output: JsonValue; isError?: boolean } | null;
+
+function toToolCallPart(
+ part: Extract<NormalizedMessagePart, { type: "tool-call" }>,
+) {
+ return {
+ id: part.toolCallId ?? "",
+ name: part.toolName,
+ arguments: part.input,
+ ...(part.toolType ? { type: part.toolType } : {}),
+ // Paired by toIOPreview below; null = no result in this observation.
+ response: null as ToolCallResponse,
+ };
+}
+
+function toToolResultMessage(
+ part: Extract<NormalizedMessagePart, { type: "tool-result" }>,
+): ChatMlMessage {
+ // Deliberately no `name`: the renderer titles messages name-over-role, and
+ // a tool result must render as a tool turn, not as a participant named
+ // after the tool. The tool name stays on the paired tool-call part.
+ return {
+ role: "tool",
+ ...(part.toolCallId ? { tool_call_id: part.toolCallId } : {}),
+ content: part.output,
+ } as ChatMlMessage;
+}
+
+type ProjectedMessage = {
+ main: ChatMlMessage | undefined;
+ toolCallEntries: ReturnType<typeof toToolCallPart>[];
+ toolResultParts: Extract<NormalizedMessagePart, { type: "tool-result" }>[];
+};
+
+function toChatMessages(message: NormalizedMessage): ProjectedMessage {
+ const contentParts: Array<string | Record<string, unknown>> = [];
+ const thinking: Array<{
+ type: "thinking";
+ content: string;
+ signature?: string;
+ }> = [];
+ const redactedThinking: Array<{ type: "redacted_thinking"; data: string }> =
+ [];
+ const jsonParts: unknown[] = [];
+ const toolCalls: ReturnType<typeof toToolCallPart>[] = [];
+ const toolResults: Extract<NormalizedMessagePart, { type: "tool-result" }>[] =
+ [];
+
+ for (const part of message.parts) {
+ switch (part.type) {
+ case "text":
+ contentParts.push(part.text);
+ break;
+ case "reasoning":
+ if (part.content.kind === "text") {
+ thinking.push({
+ type: "thinking",
+ content: part.content.text,
+ ...(part.content.signature
+ ? { signature: part.content.signature }
+ : {}),
+ });
+ } else if (
+ part.content.kind === "redacted" ||
+ part.content.kind === "encrypted"
+ ) {
+ redactedThinking.push({
+ type: "redacted_thinking",
+ data: part.content.data,
+ });
+ } else {
+ jsonParts.push(part.content.value);
+ }
+ break;
+ case "tool-call":
+ toolCalls.push(toToolCallPart(part));
+ break;
+ case "tool-result":
+ toolResults.push(part);
+ break;
+ case "file":
+ if (part.mediaType?.startsWith("image/")) {
+ contentParts.push(toImageContentPart(part));
+ } else {
+ // The existing ChatML renderer has no generic file part. Keep the
+ // complete normalized value in the passthrough JSON view instead.
+ jsonParts.push(part);
+ }
+ break;
+ case "data":
+ jsonParts.push(part.value);
+ break;
+ case "custom":
+ jsonParts.push({ kind: part.kind, value: part.value });
+ break;
+ }
+ }
+
+ const hasImages = contentParts.some((part) => typeof part !== "string");
+ const content = hasImages
+ ? contentParts.map((part) =>
+ typeof part === "string" ? { type: "text", text: part } : part,
+ )
+ : contentParts.length > 0
+ ? contentParts.join("")
+ : undefined;
+
+ const json =
+ jsonParts.length === 0
+ ? undefined
+ : jsonParts.length === 1
+ ? jsonParts[0]
+ : jsonParts;
+
+ const hasMainMessage =
+ content !== undefined ||
+ thinking.length > 0 ||
+ redactedThinking.length > 0 ||
+ toolCalls.length > 0 ||
+ json !== undefined;
+
+ const mainMessage = hasMainMessage
+ ? ({
+ role: message.role,
+ // `senderName` is deliberately not mapped to ChatML `name`: the
+ // renderer titles messages name-over-role, and this view titles by
+ // role.
+ ...(content !== undefined ? { content } : {}),
+ ...(thinking.length > 0 ? { thinking } : {}),
+ ...(redactedThinking.length > 0
+ ? { redacted_thinking: redactedThinking }
+ : {}),
+ ...(toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
+ ...(json !== undefined ? { json } : {}),
+ } as ChatMlMessage)
+ : undefined;
+
+ // Tool results stay parts here: toIOPreview pairs them into their call
+ // entries across messages before the leftovers become standalone messages.
+ return {
+ main: mainMessage,
+ toolCallEntries: toolCalls,
+ toolResultParts: toolResults,
+ };
+}
+
+/**
+ * Projects normalized I/O into the existing ChatML-shaped preview contract.
+ * This is intentionally a web-only compatibility layer; the normalized parser
+ * remains independent of React and the current rendering components.
+ */
+export function toIOPreview(
+ io: NormalizedIO,
+ parsedInput: unknown,
+): ChatMLParserResult {
+ const projected = io.messages.map((message) => ({
+ source: message.source,
+ ...toChatMessages(message),
+ }));
+
+ // Pair tool results into their call entries by id (calls and results can
+ // live in different messages). First call with an id wins; a result whose
+ // id is unknown or already answered stays a standalone tool message, so
+ // nothing is ever dropped.
+ const callEntryById = new Map<
+ string,
+ ProjectedMessage["toolCallEntries"][number]
+ >();
+ for (const { toolCallEntries } of projected) {
+ for (const entry of toolCallEntries) {
+ if (entry.id && !callEntryById.has(entry.id)) {
+ callEntryById.set(entry.id, entry);
+ }
+ }
+ }
+
+ const projectedMessages = projected.map(
+ ({ source, main, toolResultParts }) => {
+ const standaloneResults = toolResultParts.filter((part) => {
+ const entry = part.toolCallId
+ ? callEntryById.get(part.toolCallId)
+ : undefined;
+ if (!entry || entry.response !== null) return true;
+ entry.response = {
+ output: part.output,
+ ...(part.isError !== undefined ? { isError: part.isError } : {}),
+ };
+ return false;
+ });
+ return {
+ source,
+ messages: [
+ ...(main ? [main] : []),
+ ...standaloneResults.map(toToolResultMessage),
+ ],
+ };
+ },
+ );
+ const allMessages = projectedMessages.flatMap(({ messages }) => messages);
+ const inputMessageCount = projectedMessages.reduce(
+ (count, { source, messages }) =>
+ count + (source === "input" ? messages.length : 0),
+ 0,
+ );
+ const bookkeeping = computeToolCallBookkeeping(
+ allMessages,
+ inputMessageCount,
+ io.toolDefinitions.map(toToolDefinition),
+ );
+
+ return {
+ canDisplayAsChat: allMessages.length > 0,
+ allMessages,
+ // computes additionalInput via the legacy extractAdditionalInput(parsedInput) helper, which strips
+ // only the top-level keys the OLD provider adapters used to populate. This projection must be
+ // updated to manage only the keys that are additional in the context of the new provider adapters.
+ additionalInput: extractAdditionalInput(parsedInput),
+ inputMessageCount,
+ ...bookkeeping,
+ };
+}