Skip to content

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.md
new file mode 100644
index 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 total
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentSessionMetricsStrip.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionMetricsStrip.tsx
index 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 }: AgentSessionMetricsStripPr
metrics.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} />
<SessionMetricTile
id="wall-time"
label="Duration"
diff --git a/packages/trueforge-ui/src/containers/AgentSessionTimelineContainer.tsx b/packages/trueforge-ui/src/containers/AgentSessionTimelineContainer.tsx
index 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.ts
index 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.tsx
index 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.ts
index 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);
});
});