Skip to content

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

15.4 KB
Raw Blame
import type { SessionEventTimelineSegment } from './sessionEventTimeline.js';

/**
 * Pure layout helpers for the Sessions timeline.
 *
 * Segment construction owns event meaning; this module owns visual grouping,
 * lane allocation, and the compressed time axis. Keeping these calculations
 * outside React/Chart.js makes the rendering rules deterministic and testable.
 */

/** Minimal interval shared by bars, compressed gaps, and grouped tool calls. */
export type TimelineGap = {
  startMs: number;
  endMs: number;
};

export type TimelineTurnRange = {
  turnIndex: number;
  startMs: number;
  endMs: number;
  ordinal: number;
};

export type TimelineLayout = {
  turnStartsMs: number[];
  turnOrdinals: Map<number, number>;
  turnRanges: TimelineTurnRange[];
};

export type TimelineTurnBar = TimelineTurnRange & {
  id: string;
  durationMs: number;
};

export type TimelineSubAgentBar = SessionEventTimelineSegment & {
  lane: number;
  visualEndMs: number;
};

export type TimelineSubAgentLane = {
  threadId: string;
  lane: number;
  track: TimelineSubAgentBar;
  segments: SessionEventTimelineSegment[];
};

export type TimelineToolCallGroup = TimelineGap & {
  id: string;
  segments: SessionEventTimelineSegment[];
};

export type TimelineSubAgentGroup = TimelineGap & {
  id: string;
  barId: string;
  segments: SessionEventTimelineSegment[];
};

export type TimelineMarkerGroup = TimelineGap & {
  id: string;
  segments: SessionEventTimelineSegment[];
};

export const TIMELINE_TYPE = {
  turn: 'turn',
  event: 'event',
  markerGroup: 'markerGroup',
  toolCallGroup: 'toolCallGroup',
  subAgentGroup: 'subAgentGroup',
} as const;

export type TimelineHoverTarget =
  | { type: typeof TIMELINE_TYPE.turn; bar: TimelineTurnBar }
  | { type: typeof TIMELINE_TYPE.event; segment: SessionEventTimelineSegment }
  | { type: typeof TIMELINE_TYPE.markerGroup; group: TimelineMarkerGroup }
  | { type: typeof TIMELINE_TYPE.toolCallGroup; group: TimelineToolCallGroup; subAgentLabel?: string }
  | { type: typeof TIMELINE_TYPE.subAgentGroup; group: TimelineSubAgentGroup };

/** Stable identity used to avoid replacing tooltip state while hovering the same bar. */
export function getTimelineHoverTargetId(target: TimelineHoverTarget | null): string {
  if (target == null) return '';
  if (target.type === TIMELINE_TYPE.turn) return target.bar.id;
  if (target.type === TIMELINE_TYPE.event) return target.segment.id;
  return target.group.id;
}

/** Convert an interval to Chart.js's floating horizontal-bar data shape. */
export function getTimelineRange({ startMs, endMs }: TimelineGap): [number, number] {
  return [startMs, endMs];
}

/** Collapse point events that share (or nearly share) a chart timestamp into one marker and tooltip. */
export function groupCoincidentTimelineMarkers(
  segments: SessionEventTimelineSegment[],
  { toleranceMs = 0 }: { toleranceMs?: number } = {},
): TimelineMarkerGroup[] {
  const markers = segments
    .flatMap((segment, index) => (segment.isMarker ? [{ segment, index }] : []))
    .sort((left, right) => left.segment.startMs - right.segment.startMs || left.index - right.index)
    .map(({ segment }) => segment);

  const groups: TimelineMarkerGroup[] = [];
  for (const segment of markers) {
    const current = groups.at(-1);
    if (current != null && segment.startMs - current.startMs <= toleranceMs) {
      current.segments.push(segment);
      continue;
    }
    groups.push({
      id: segment.id,
      startMs: segment.startMs,
      endMs: segment.startMs,
      segments: [segment],
    });
  }

  return groups.map(group => ({
    ...group,
    id: `marker-group-${group.segments.map(segment => segment.id).join('-')}`,
  }));
}

function timelineAxisUnit(totalMs: number): { divisorMs: number; suffix: string } {
  if (totalMs < 1_000) return { divisorMs: 1, suffix: 'ms' };
  if (totalMs < 60_000) return { divisorMs: 1_000, suffix: 's' };
  if (totalMs < 3_600_000) return { divisorMs: 60_000, suffix: 'm' };
  return { divisorMs: 3_600_000, suffix: 'h' };
}

/** Format an axis label as milliseconds, seconds, minutes, or hours by elapsed time. */
export function formatTimelineAxisDuration(durationMs: number): string {
  const unit = timelineAxisUnit(durationMs);
  return `${Number((durationMs / unit.divisorMs).toFixed(2))}${unit.suffix}`;
}

const DEFAULT_AXIS_TICK_TARGET = 8;
const AXIS_TICK_PX = 120;

export type TimelineTurnStretch = {
  /** Pixels added so the turn bar reaches the minimum. Indexed by ordinal. */
  extraPx: number[];
  /** Stretches offsets inside the turn. `1` when the bar is already wide enough. */
  scale: number[];
  /** Sum of `extraPx` before this ordinal. */
  leadingExtraPx: number[];
};

/**
 * Give every turn at least `minTurnBarPx` without changing how long turns share the pane.
 * Short turns stretch internally; later turns shift right by that extra width.
 */
export function getTimelineTurnStretch({
  durationsMs,
  msPerPx,
  minTurnBarPx,
  markerPx,
}: {
  durationsMs: number[];
  msPerPx: number;
  minTurnBarPx: number;
  markerPx: number;
}): TimelineTurnStretch {
  const extraPx: number[] = [];
  const scale: number[] = [];
  const leadingExtraPx: number[] = [];
  let leading = 0;
  for (const durationMs of durationsMs) {
    leadingExtraPx.push(leading);
    const durationPx = msPerPx > 0 ? Math.max(0, durationMs) / msPerPx : 0;
    const extra = Math.max(0, minTurnBarPx - (durationPx + markerPx));
    extraPx.push(extra);
    scale.push(durationPx > 0 ? (durationPx + extra) / durationPx : 1);
    leading += extra;
  }
  return { extraPx, scale, leadingExtraPx };
}

/** Map a real timestamp onto the chart axis, including turn gaps and short-turn stretch. */
export function timelineChartMs({
  realMs,
  turnStartMs,
  turnEndMs,
  ordinal,
  stretch,
  msPerPx,
  turnGapPx,
}: {
  realMs: number;
  turnStartMs: number;
  turnEndMs: number;
  ordinal: number;
  stretch: TimelineTurnStretch;
  msPerPx: number;
  turnGapPx: number;
}): number {
  const scaleFactor = stretch.scale[ordinal] ?? 1;
  const shiftMs = (stretch.leadingExtraPx[ordinal] ?? 0) * msPerPx + ordinal * turnGapPx * msPerPx;
  if (realMs < turnStartMs) return realMs + shiftMs;
  if (realMs > turnEndMs) {
    return turnStartMs + (turnEndMs - turnStartMs) * scaleFactor + shiftMs + (realMs - turnEndMs);
  }
  return turnStartMs + (realMs - turnStartMs) * scaleFactor + shiftMs;
}

/** About one label per 120px, and never fewer than the default eight. */
export function getTimelineAxisTickTarget(chartWidthPx?: number): number {
  if (chartWidthPx == null || chartWidthPx <= 0) return DEFAULT_AXIS_TICK_TARGET;
  return Math.max(DEFAULT_AXIS_TICK_TARGET, Math.round(chartWidthPx / AXIS_TICK_PX));
}

function getCleanAxisStepMs({ totalMs, tickTarget }: { totalMs: number; tickTarget: number }): number {
  const { divisorMs } = timelineAxisUnit(totalMs);
  const target = totalMs / divisorMs / tickTarget;
  if (divisorMs >= 60_000 && target < 1) return Math.max(0.25, Math.ceil(target * 4) / 4) * divisorMs;
  const integerTarget = Math.max(1, target);
  const magnitude = 10 ** Math.floor(Math.log10(integerTarget));
  const normalized = integerTarget / magnitude;
  const multiplier = normalized <= 1 ? 1 : normalized <= 2 ? 2 : normalized <= 5 ? 5 : 10;
  return multiplier * magnitude * divisorMs;
}

/** Generate clean active-time ticks, translated around fixed visual turn separators. */
export function buildTimelineAxisTicks({
  activeTotalMs,
  turnStartsMs,
  turnGapMs,
  chartWidthPx,
}: {
  activeTotalMs: number;
  turnStartsMs: number[];
  turnGapMs: number;
  chartWidthPx?: number;
}): Array<{ value: number }> {
  const stepMs = getCleanAxisStepMs({ totalMs: activeTotalMs, tickTarget: getTimelineAxisTickTarget(chartWidthPx) });
  const activeTicks: number[] = [];
  for (let activeMs = 0; activeMs < activeTotalMs; activeMs += stepMs) activeTicks.push(activeMs);
  const lastRegularTick = activeTicks.at(-1);
  if (lastRegularTick != null && lastRegularTick > 0 && activeTotalMs - lastRegularTick < stepMs / 4) {
    activeTicks.pop();
  }
  if (activeTicks.at(-1) !== activeTotalMs) activeTicks.push(activeTotalMs);
  return activeTicks.map(activeMs => ({
    value: activeMs + turnStartsMs.slice(1).filter(turnStartMs => turnStartMs <= activeMs).length * turnGapMs,
  }));
}

/**
 * Derive one background range per turn from all of that turn's segments.
 *
 * Turn numbers can be sparse after filtering or incomplete server data, so
 * `ordinal` is a dense visual position while `turnIndex` remains the source id.
 */
export function getTimelineLayout(segments: SessionEventTimelineSegment[]): TimelineLayout {
  const rangesByTurnIndex = new Map<number, TimelineGap>();

  for (const segment of segments) {
    const range = rangesByTurnIndex.get(segment.turnIndex);
    if (range) {
      range.startMs = Math.min(range.startMs, segment.startMs);
      range.endMs = Math.max(range.endMs, segment.endMs);
    } else {
      rangesByTurnIndex.set(segment.turnIndex, { startMs: segment.startMs, endMs: segment.endMs });
    }
  }

  const ranges = Array.from(rangesByTurnIndex.entries()).sort(([left], [right]) => left - right);
  return {
    turnStartsMs: ranges.map(([, range]) => range.startMs),
    turnOrdinals: new Map(ranges.map(([turnIndex], ordinal) => [turnIndex, ordinal])),
    turnRanges: ranges.map(([turnIndex, range], ordinal) => ({
      turnIndex,
      startMs: range.startMs,
      endMs: range.endMs,
      ordinal,
    })),
  };
}

/** Touching endpoints do not overlap, allowing adjacent bars to share a row. */
function segmentsOverlap(left: SessionEventTimelineSegment, right: SessionEventTimelineSegment): boolean {
  return left.startMs < right.endMs && right.startMs < left.endMs;
}

/** Merge transitively overlapping sub-agent runs into summary bars for the main event row. */
export function mergeOverlappingSubAgentSegments(
  segments: SessionEventTimelineSegment[],
): SessionEventTimelineSegment[] {
  const merged: SessionEventTimelineSegment[] = [];
  for (const segment of [...segments].sort(
    (left, right) => left.turnIndex - right.turnIndex || left.startMs - right.startMs || left.endMs - right.endMs,
  )) {
    const current = merged.at(-1);
    if (current == null || current.turnIndex !== segment.turnIndex || !segmentsOverlap(current, segment)) {
      merged.push({ ...segment });
      continue;
    }
    current.endMs = Math.max(current.endMs, segment.endMs);
  }
  return merged;
}

/**
 * Merge transitively overlapping tool calls within the same turn and thread.
 *
 * Concurrent calls would otherwise draw on top of one another in the main
 * event row. The merged bar spans the union and its tooltip lists every member.
 * Calls from different turns/threads never merge even if timestamps overlap.
 */
export function groupOverlappingToolCalls(segments: SessionEventTimelineSegment[]): TimelineToolCallGroup[] {
  const groups: TimelineToolCallGroup[] = [];
  for (const segment of [...segments].sort((left, right) => left.startMs - right.startMs || left.endMs - right.endMs)) {
    const current = groups.at(-1);
    if (
      current == null ||
      current.segments[0]?.turnIndex !== segment.turnIndex ||
      current.segments[0]?.threadId !== segment.threadId ||
      segment.startMs >= current.endMs
    ) {
      groups.push({
        id: `tool-call-group-${segment.id}`,
        startMs: segment.startMs,
        endMs: segment.endMs,
        segments: [segment],
      });
      continue;
    }
    current.endMs = Math.max(current.endMs, segment.endMs);
    current.segments.push(segment);
  }
  return groups;
}

// Each merged main-row bar owns the runs represented by its full interval.
export function getSubAgentHoverGroups({
  bars,
  subAgentSegments,
}: {
  bars: SessionEventTimelineSegment[];
  subAgentSegments: SessionEventTimelineSegment[];
}): TimelineSubAgentGroup[] {
  return bars.map(bar => ({
    id: `sub-agent-group-${bar.id}`,
    barId: bar.id,
    startMs: bar.startMs,
    endMs: bar.endMs,
    segments: subAgentSegments.filter(
      segment => segment.turnIndex === bar.turnIndex && (segment.id === bar.id || segmentsOverlap(bar, segment)),
    ),
  }));
}

/**
 * Assign sub-agent tracks to the first reusable non-overlapping lane and attach
 * each thread's child events to that track.
 *
 * `minWidthMs` matches the chart's minimum pixel width in time units, preventing
 * visually widened markers from colliding even when their raw durations do not.
 */
export function getSubAgentLanes({
  subAgentSegments,
  threadSegments,
  minWidthMs,
}: {
  subAgentSegments: SessionEventTimelineSegment[];
  threadSegments: SessionEventTimelineSegment[];
  minWidthMs: number;
}): TimelineSubAgentLane[] {
  const laneEndsMs: number[] = [];
  const tracks = [...subAgentSegments]
    .sort((left, right) => left.startMs - right.startMs)
    .map(segment => {
      const visualEndMs = Math.max(segment.endMs, segment.startMs + minWidthMs);
      const freeLane = laneEndsMs.findIndex(laneEndMs => laneEndMs <= segment.startMs);
      const lane = freeLane === -1 ? laneEndsMs.length : freeLane;
      laneEndsMs[lane] = visualEndMs;
      return { ...segment, id: `${segment.id}-lane`, lane, visualEndMs };
    });

  const childrenByThreadId = new Map<string, SessionEventTimelineSegment[]>();
  for (const segment of threadSegments) {
    if (segment.type === 'sub_agent') continue;
    const children = childrenByThreadId.get(segment.threadId);
    if (children) children.push(segment);
    else childrenByThreadId.set(segment.threadId, [segment]);
  }

  return tracks.map(track => ({
    threadId: track.threadId,
    lane: track.lane,
    track,
    segments: childrenByThreadId.get(track.threadId) ?? [],
  }));
}

/**
 * Collapse real idle time between turns while preserving all within-turn
 * offsets and durations.
 *
 * Session history may contain minutes or days between user messages. Displaying
 * that idle time would squeeze useful execution bars into a few pixels, so each
 * turn is translated to begin where the previous one ended. The chart adds a
 * small fixed visual separator afterward.
 */
export function compressInterTurnGaps(segments: SessionEventTimelineSegment[]): SessionEventTimelineSegment[] {
  const rangesByTurnIndex = new Map<number, { turnIndex: number; startMs: number; endMs: number }>();
  for (const segment of segments) {
    const range = rangesByTurnIndex.get(segment.turnIndex);
    if (range) {
      range.startMs = Math.min(range.startMs, segment.startMs);
      range.endMs = Math.max(range.endMs, segment.endMs);
    } else {
      rangesByTurnIndex.set(segment.turnIndex, {
        turnIndex: segment.turnIndex,
        startMs: segment.startMs,
        endMs: segment.endMs,
      });
    }
  }

  const shiftsByTurnIndex = new Map<number, number>();
  let previousEndMs = 0;
  for (const [rangeIndex, range] of Array.from(rangesByTurnIndex.values())
    .sort((left, right) => left.turnIndex - right.turnIndex)
    .entries()) {
    const targetStartMs = rangeIndex === 0 ? 0 : previousEndMs;
    const shiftMs = targetStartMs - range.startMs;
    shiftsByTurnIndex.set(range.turnIndex, shiftMs);
    previousEndMs = range.endMs + shiftMs;
  }

  return segments.map(segment => {
    const shiftMs = shiftsByTurnIndex.get(segment.turnIndex) ?? 0;
    return { ...segment, startMs: segment.startMs + shiftMs, endMs: segment.endMs + shiftMs };
  });
}

/** Translate a chart coordinate back to active elapsed time across visual turn separators. */
export function getActiveTimelineMs(valueMs: number, gaps: TimelineGap[]): number {
  let activeMs = valueMs;
  for (const gap of gaps) {
    activeMs -= Math.max(0, Math.min(valueMs, gap.endMs) - gap.startMs);
  }
  return Math.max(0, activeMs);
}