Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

6.5 KB
Raw Blame
import { MAIN_THREAD_ID, getSessionEventColor, type SessionEventTimelineSegment } from './sessionEventTimeline.js';
import type { SessionTurnView } from './sessionTurnViews.js';

export type SessionMetricBarDatum = {
  label: string;
  value: number;
  color: string;
};

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;
  contextTokens: number;
  toolCalls: number;
  subAgents: number;
  errors: number;
  timeBreakdown: SessionMetricBarDatum[];
  costPerTurn: SessionMetricBarDatum[];
  tokenBreakdown: SessionMetricBarDatum[];
  contextByTurn: SessionMetricBarDatum[];
  toolCallFrequency: SessionMetricBarDatum[];
};

/** Optional getSession overrides — lineage turn count always comes from events. */
export type SessionMetricsHint = {
  totalTurns?: number;
  totalCostInUsd?: number;
  totalDurationMs: number;
};

function segmentDurationMs(segment: SessionEventTimelineSegment): number {
  return Math.max(0, segment.endMs - segment.startMs);
}

function turnHasMetrics(turn: SessionTurnView): boolean {
  return (
    turn.totalTokens != null ||
    turn.inputTokens != null ||
    turn.outputTokens != null ||
    turn.cachedTokens != null ||
    turn.totalCostInUsd != null
  );
}

export function buildSessionMetrics({
  turns,
  segments,
  sessionMetrics,
}: {
  turns: SessionTurnView[];
  segments: SessionEventTimelineSegment[];
  sessionMetrics?: SessionMetricsHint;
}): SessionMetrics {
  let derivedWallTimeMs = 0;
  let derivedCostUsd = 0;
  let hasDerivedCost = false;
  let totalTokens = 0;
  let totalUncachedInputTokens = 0;
  let totalOutputTokens = 0;
  let totalCachedTokens = 0;
  // Aggregate by display band so MCP-auth resumes don't emit duplicate T1 chart keys.
  const bandCostUsd = new Map<number, number>();
  const bandTokens = new Map<number, number>();

  for (const turn of turns) {
    derivedWallTimeMs += turn.durationMs ?? 0;
    if (!turnHasMetrics(turn)) {
      if (!bandCostUsd.has(turn.turnNumber)) bandCostUsd.set(turn.turnNumber, 0);
      if (!bandTokens.has(turn.turnNumber)) bandTokens.set(turn.turnNumber, 0);
      continue;
    }

    // Prefer canonical turn fields from sessionTurnViews (uncached input already).
    const uncachedInputTokens = turn.inputTokens ?? 0;
    const outputTokens = turn.outputTokens ?? 0;
    const cachedTokens = turn.cachedTokens ?? 0;
    const turnTotalTokens = turn.totalTokens ?? uncachedInputTokens + cachedTokens + outputTokens;
    const turnCostUsd = turn.totalCostInUsd;

    if (turnCostUsd != null) {
      derivedCostUsd += turnCostUsd;
      hasDerivedCost = true;
    }
    totalTokens += turnTotalTokens;
    totalUncachedInputTokens += uncachedInputTokens;
    totalOutputTokens += outputTokens;
    totalCachedTokens += cachedTokens;
    bandCostUsd.set(turn.turnNumber, (bandCostUsd.get(turn.turnNumber) ?? 0) + (turnCostUsd ?? 0));
    bandTokens.set(turn.turnNumber, (bandTokens.get(turn.turnNumber) ?? 0) + turnTotalTokens);
  }

  const costPerTurn: SessionMetricBarDatum[] = [];
  const contextByTurn: SessionMetricBarDatum[] = [];
  let contextTokens = 0;
  for (const turnNumber of [...bandTokens.keys()].sort((left, right) => left - right)) {
    const label = `T${turnNumber}`;
    contextTokens += bandTokens.get(turnNumber) ?? 0;
    costPerTurn.push({
      label,
      value: bandCostUsd.get(turnNumber) ?? 0,
      color: getSessionEventColor('tool_call'),
    });
    contextByTurn.push({ label, value: contextTokens, color: getSessionEventColor('model') });
  }

  const modelTimeMs = segments
    .filter(segment => segment.type === 'model')
    .reduce((sum, segment) => sum + segmentDurationMs(segment), 0);
  const toolTimeMs = segments
    .filter(segment => segment.type === 'tool_call')
    .reduce((sum, segment) => sum + segmentDurationMs(segment), 0);
  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; lineage turn count is always from events.
  const wallTimeMs = sessionMetrics != null ? sessionMetrics.totalDurationMs : derivedWallTimeMs;
  const overheadTimeMs = Math.max(0, wallTimeMs - modelTimeMs - toolTimeMs - waitingTimeMs);

  const toolCallCounts = new Map<string, number>();
  for (const segment of segments) {
    if (segment.type !== 'tool_call' || segment.threadId !== MAIN_THREAD_ID) continue;
    toolCallCounts.set(segment.description, (toolCallCounts.get(segment.description) ?? 0) + 1);
  }
  const toolCallFrequency = Array.from(toolCallCounts, ([label, value]) => ({
    label,
    value,
    color: getSessionEventColor('tool_call'),
  })).sort((left, right) => right.value - left.value);

  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: lineageTurns,
    ...(sessionTotalTurns == null ? {} : { sessionTotalTurns }),
    wallTimeMs,
    ...(totalCostUsd == null ? {} : { totalCostUsd }),
    totalTokens,
    contextTokens,
    toolCalls: toolCallFrequency.reduce((sum, toolCall) => sum + toolCall.value, 0),
    subAgents: segments.filter(segment => segment.type === 'sub_agent').length,
    errors: segments.filter(segment => segment.type === 'error').length,
    timeBreakdown: [
      { label: 'model', value: modelTimeMs, color: getSessionEventColor('model') },
      { label: 'tools', value: toolTimeMs, color: getSessionEventColor('tool_call') },
      { label: 'waiting on human', value: waitingTimeMs, color: getSessionEventColor('approval') },
      { label: 'overhead', value: overheadTimeMs, color: getSessionEventColor('system') },
    ],
    costPerTurn,
    tokenBreakdown: [
      { label: 'input', value: totalUncachedInputTokens, color: getSessionEventColor('model') },
      { label: 'output', value: totalOutputTokens, color: getSessionEventColor('user') },
      { label: 'cached', value: totalCachedTokens, color: getSessionEventColor('sub_agent') },
    ],
    contextByTurn,
    toolCallFrequency,
  };
}