The open-source agent harness - the runtime layer that turns an LLM into a working agent.
chore: add session-level turn count display and tooltip explanation (#997)
harshil-20967a818268cd21
diff --git a/.changeset/session-lineage-turn-count.md b/.changeset/session-lineage-turn-count.mdnew file mode 100644index 000000000..629729654--- /dev/null+++ b/.changeset/session-lineage-turn-count.md@@ -0,0 +1,5 @@+---+"@truefoundry/trueforge-ui": patch+---++Explain higher session-level turn counts when the tip lineage is shorter than session totaldiff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentSessionMetricsStrip.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionMetricsStrip.tsxindex f1f06fcc7..6fcc1c52e 100644--- a/packages/trueforge-ui/src/atoms/agent-details/AgentSessionMetricsStrip.tsx+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionMetricsStrip.tsx@@ -15,6 +15,9 @@ import {} from './AgentSessionMetricCharts.js';import type { AgentSessionMetricsStripProps } from './types.js';+const SESSION_LINEAGE_TURNS_TOOLTIP =+ 'Some turns in this session were edited or retried. Showing only the latest lineage of the session';+function SessionMetricTile({id,label,@@ -23,7 +26,7 @@ function SessionMetricTile({}: {id: string;label: string;- value: string | number;+ value: ReactNode;tooltip?: ReactNode;}) {const content = (@@ -46,6 +49,58 @@ function SessionMetricTile({);}+function SessionTurnsMetricTile({+ lineageTurns,+ sessionTotalTurns,+}: {+ lineageTurns: number;+ sessionTotalTurns?: number;+}) {+ const showLineageSplit = sessionTotalTurns != null && sessionTotalTurns > lineageTurns;+ const label = lineageTurns > 1 || (sessionTotalTurns != null && sessionTotalTurns > 1) ? 'Turns' : 'Turn';++ const value = showLineageSplit ? (+ <span className="inline-flex h-4 items-center gap-2">+ <span className="leading-none">+ <span className="text-primary-button-bg">{lineageTurns} </span>+ <span className="text-text-primary">/ {sessionTotalTurns}</span>+ </span>+ <Icon+ name="circle-exclamation"+ size={16}+ className="size-4 shrink-0 text-warning-bg"+ data-testid="icon-circle-exclamation"+ />+ </span>+ ) : (+ lineageTurns+ );++ const tile = (+ <div+ className="h-full w-full border-b border-r border-border bg-primary-bg px-3 py-2"+ data-slot="session-metric-turns"+ >+ <div className="mb-0.5 flex items-center gap-1 text-[0.625rem] font-medium uppercase tracking-wider text-text-secondary">+ {label}+ </div>+ <div className="flex items-center pt-1 text-base font-medium leading-none text-text-primary">{value}</div>+ </div>+ );++ if (!showLineageSplit) return tile;+ return (+ <LightTooltip+ title={SESSION_LINEAGE_TURNS_TOOLTIP}+ side="bottom"+ triggerClassName="block w-full"+ className="max-w-56 whitespace-normal"+ >+ {tile}+ </LightTooltip>+ );+}+export function AgentSessionMetricsStrip({ metrics }: AgentSessionMetricsStripProps) {return (<div className="@container overflow-hidden border-b border-border" data-slot="agent-session-metrics-strip">@@ -55,7 +110,7 @@ export function AgentSessionMetricsStrip({ metrics }: AgentSessionMetricsStripPrmetrics.totalCostUsd == null ? '@min-[48rem]:grid-cols-7' : '@min-[48rem]:grid-cols-8',)}>- <SessionMetricTile id="turns" label={metrics.totalTurns > 1 ? 'Turns' : 'Turn'} value={metrics.totalTurns} />+ <SessionTurnsMetricTile lineageTurns={metrics.totalTurns} sessionTotalTurns={metrics.sessionTotalTurns} /><SessionMetricTileid="wall-time"label="Duration"diff --git a/packages/trueforge-ui/src/containers/AgentSessionTimelineContainer.tsx b/packages/trueforge-ui/src/containers/AgentSessionTimelineContainer.tsxindex 13eeef889..91508a37c 100644--- a/packages/trueforge-ui/src/containers/AgentSessionTimelineContainer.tsx+++ b/packages/trueforge-ui/src/containers/AgentSessionTimelineContainer.tsx@@ -141,6 +141,7 @@ export type AgentSessionTimelineContainerProps = {events: SessionEventItem[];contentMaxWidth?: string;sessionMetrics?: {+ totalTurns?: number;totalCostInUsd?: number;totalDurationMs: number;};diff --git a/packages/trueforge-ui/src/utils/buildSessionMetrics.ts b/packages/trueforge-ui/src/utils/buildSessionMetrics.tsindex 543c13a17..bcab47fc4 100644--- a/packages/trueforge-ui/src/utils/buildSessionMetrics.ts+++ b/packages/trueforge-ui/src/utils/buildSessionMetrics.ts@@ -8,7 +8,13 @@ export type SessionMetricBarDatum = {};export type SessionMetrics = {+ /** Tip-lineage turn count from loaded events. */totalTurns: number;+ /**+ * Session-level turn total from getSession when it exceeds the tip lineage+ * (edit/retry abandoned branches). Omitted when equal or unavailable.+ */+ sessionTotalTurns?: number;wallTimeMs: number;totalCostUsd?: number;totalTokens: number;@@ -23,8 +29,9 @@ export type SessionMetrics = {toolCallFrequency: SessionMetricBarDatum[];};-/** Optional getSession overrides for wall time and cost only — turn count always comes from events. */+/** Optional getSession overrides — lineage turn count always comes from events. */export type SessionMetricsHint = {+ totalTurns?: number;totalCostInUsd?: number;totalDurationMs: number;};@@ -113,7 +120,7 @@ export function buildSessionMetrics({const waitingTimeMs = segments.filter(segment => segment.type === 'waiting_on_human' || segment.type === 'approval').reduce((sum, segment) => sum + segmentDurationMs(segment), 0);- // Detail session metrics may override wall time and cost; turn count is always from events.+ // Detail session metrics may override wall time and cost; lineage turn count is always from events.const wallTimeMs = sessionMetrics != null ? sessionMetrics.totalDurationMs : derivedWallTimeMs;const overheadTimeMs = Math.max(0, wallTimeMs - modelTimeMs - toolTimeMs - waitingTimeMs);@@ -131,8 +138,16 @@ export function buildSessionMetrics({const totalCostUsd =sessionMetrics != null ? sessionMetrics.totalCostInUsd : hasDerivedCost ? derivedCostUsd : undefined;+ const lineageTurns = turns.length;+ const hintTotalTurns = sessionMetrics?.totalTurns;+ const sessionTotalTurns =+ hintTotalTurns != null && Number.isFinite(hintTotalTurns) && hintTotalTurns > lineageTurns+ ? hintTotalTurns+ : undefined;+return {- totalTurns: turns.length,+ totalTurns: lineageTurns,+ ...(sessionTotalTurns == null ? {} : { sessionTotalTurns }),wallTimeMs,...(totalCostUsd == null ? {} : { totalCostUsd }),totalTokens,diff --git a/packages/trueforge-ui/test/atoms/AgentSessionMetricsStrip.test.tsx b/packages/trueforge-ui/test/atoms/AgentSessionMetricsStrip.test.tsxindex 653e42893..c1a27cb3e 100644--- a/packages/trueforge-ui/test/atoms/AgentSessionMetricsStrip.test.tsx+++ b/packages/trueforge-ui/test/atoms/AgentSessionMetricsStrip.test.tsx@@ -83,6 +83,30 @@ describe('AgentSessionMetricsStrip', () => {expect(tooltip!.className).toMatch(/pointer-events-auto/);},);++ it('shows lineage / session total with explanation when session total exceeds lineage', () => {+ render(<AgentSessionMetricsStrip metrics={{ ...metrics, totalTurns: 2, sessionTotalTurns: 4 }} />);+ const turnsTile = document.querySelector('[data-slot="session-metric-turns"]');+ expect(turnsTile).not.toBeNull();+ expect(turnsTile).toHaveTextContent('2');+ expect(turnsTile).toHaveTextContent('/ 4');+ expect(screen.getByTestId('icon-circle-exclamation')).toBeInTheDocument();+ expect(screen.queryByText('7')).not.toBeInTheDocument();++ fireEvent.mouseEnter(turnsTile!);+ const tooltip = document.querySelector('[role="tooltip"]');+ expect(tooltip).not.toBeNull();+ expect(tooltip).toHaveTextContent(+ 'Some turns in this session were edited or retried. Showing only the latest lineage of the session',+ );+ });++ it('omits lineage split and warning when session total matches lineage', () => {+ render(<AgentSessionMetricsStrip metrics={{ ...metrics, totalTurns: 2, sessionTotalTurns: undefined }} />);+ expect(screen.getByText('2')).toBeInTheDocument();+ expect(screen.queryByText('/ 2')).not.toBeInTheDocument();+ expect(screen.queryByTestId('icon-circle-exclamation')).not.toBeInTheDocument();+ });});describe('CostBreakdownRows', () => {diff --git a/packages/trueforge-ui/test/utils/sessionEventTimeline.test.ts b/packages/trueforge-ui/test/utils/sessionEventTimeline.test.tsindex 3994f38d0..049726e6f 100644--- a/packages/trueforge-ui/test/utils/sessionEventTimeline.test.ts+++ b/packages/trueforge-ui/test/utils/sessionEventTimeline.test.ts@@ -928,6 +928,7 @@ describe('buildSessionMetrics', () => {assert.equal(resumeModel?.startMs, 1_500);const metrics = buildSessionMetrics({ turns, segments });assert.equal(metrics.totalTurns, 2);+ assert.equal(metrics.sessionTotalTurns, undefined);assert.equal(metrics.toolCalls, 3);assert.equal(metrics.totalTokens, 1000);assert.deepEqual(@@ -935,5 +936,20 @@ describe('buildSessionMetrics', () => {['T1'],);assert.ok(Math.abs((metrics.costPerTurn[0]?.value ?? 0) - 0.1) < 1e-9);++ const withSessionTotal = buildSessionMetrics({+ turns,+ segments,+ sessionMetrics: { totalTurns: 4, totalDurationMs: 6_000 },+ });+ assert.equal(withSessionTotal.totalTurns, 2);+ assert.equal(withSessionTotal.sessionTotalTurns, 4);++ const matchedSessionTotal = buildSessionMetrics({+ turns,+ segments,+ sessionMetrics: { totalTurns: 2, totalDurationMs: 6_000 },+ });+ assert.equal(matchedSessionTotal.sessionTotalTurns, undefined);});});