Skip to content

Replay your coding agent sessions as a map and a timeline

23.4 KB
Raw Blame
import { srcSeqOf } from '@/core/sessionMapModel';
import {
  useCallback,
  useEffect,
  useMemo,
  useRef,
  useState,
  useSyncExternalStore,
  type ReactNode,
} from 'react';
import { CalendarBlankIcon, MapTrifold } from '@phosphor-icons/react';
import {
  parseAsInteger,
  parseAsString,
  parseAsStringEnum,
  useQueryState,
  useQueryStates,
} from 'nuqs';
import type {
  SessionExplorerSession,
  SessionMap,
} from '@/core/schema';
import { SessionExplorerError } from '@/data/errors';
import { dedupeSessions } from '@/data/parse';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from '@/components/ui/select';
import { EmptyState } from '@/components/EmptyState';
import { ErrorBoundary } from '@/components/ErrorBoundary';
import { cn } from '@/lib/utils';
import { useDebounce } from '@/hooks/useDebounce';
import {
  useSessionExplorerMap,
  useSessionExplorerSessions,
  useSessionExplorerStatus,
} from '@/data/hooks';
import { WINDOW_OPTIONS, type WindowKey } from '@/core/windowOptions';
import { ExplorerToolbar } from './ExplorerToolbar';
import { ExplorerSidebar, MapPane, type SidebarCtl } from './MapPlayerParts';
import { SessionHeader } from './SessionHeader';
import { SessionList } from './SessionList';
import {
  InlineError,
  MapSkeleton,
  SessionExplorerSkeleton,
  SidePanelsSkeleton,
} from './SessionExplorerStates';
import {
  SessionListHeader,
  SidebarRail,
  SubagentInspector,
} from './SessionSidebar';
import { InsightsPanel, SidePanels } from './SidePanels';
import { TimelineDock } from './TimelineDock';
import {
  SIDEBAR_TABS,
  agentOptions,
  agentOptionsInScope,
  emptyScopeDescription,
  getSidebarCollapsed,
  getSidebarCollapsedServer,
  hasScopeFilter,
  setSidebarCollapsed,
  subscribeSidebarCollapsed,
  type SidebarTab,
} from '@/core/sessionLayout';
import type { TreeNode } from '@/core/sessionMapModel';
import {
  CLEAR_SCOPE_PARAMS,
  SCOPE_PARAMS,
  deriveScopeDoc,
  hasReplayEvents,
  modelUsage,
  scopedModelUsage,
  taskNoun,
} from '@/core/sessionScope';
import { useWindowRange } from '@/data/windowRange';
import { useEventCategories } from './useEventCategories';
import { useExplorerScope, type ExplorerScope } from './useExplorerScope';
import { useMapModel, usePlaybackWindow } from './usePlaybackWindow';

interface Props {
  /** the window selector's value; the list follows it */
  windowKey: WindowKey;
  /** the window select lives in the sessions sidebar */
  onWindowChange?: (key: WindowKey) => void;
  /** optional control under the "No session maps yet" empty state (e.g. an
   * "Open a map file" button) */
  emptyAction?: ReactNode;
}

/** The sessions in the window (search-filtered), the effective selection,
 * and its map. */
function useExplorerSessions(windowKey: WindowKey) {
  const [search, setSearch] = useQueryState(
    'sq',
    parseAsString.withDefault('')
  );
  const [selected, setSelected] = useQueryState('session', parseAsString);
  const debouncedSearch = useDebounce(search.trim(), 300);
  const range = useWindowRange(windowKey);
  const list = useSessionExplorerSessions(debouncedSearch, range);
  const sessions = useMemo<SessionExplorerSession[]>(
    () =>
      dedupeSessions(list.data?.pages.flatMap((pg) => pg.sessions) ?? []).filter(
        (s) => s.calls > 0
      ),
    [list.data]
  );
  const listIds = useMemo(() => sessions.map((s) => s.sessionId), [sessions]);
  const selectedId = selected || sessions[0]?.sessionId || null;
  const selectedRow = sessions.find((s) => s.sessionId === selectedId) ?? null;
  const mapQuery = useSessionExplorerMap(selectedId, listIds);
  return {
    search,
    setSearch,
    selected,
    setSelected,
    debouncedSearch,
    list,
    sessions,
    selectedId,
    selectedRow,
    mapQuery,
  };
}

type MapQuery = ReturnType<typeof useSessionExplorerMap>;

function WindowSelect({
  windowKey,
  onChange,
}: {
  windowKey: WindowKey;
  onChange: (key: WindowKey) => void;
}) {
  return (
    <Select
      value={windowKey}
      // label lookup for SelectValue (otherwise it renders the raw key)
      items={WINDOW_OPTIONS.map((o) => ({ value: o.key, label: o.label }))}
      onValueChange={(v: string | null) => {
        if (v) onChange(v as WindowKey);
      }}
    >
      <SelectTrigger
        aria-label="Select time window"
        className="h-8 w-full gap-2"
      >
        <CalendarBlankIcon
          size={14}
          className="shrink-0 text-ds-text-subtle"
          weight="duotone"
        />
        <SelectValue />
      </SelectTrigger>
      <SelectContent align="start">
        {WINDOW_OPTIONS.map((opt) => (
          <SelectItem key={opt.key} value={opt.key}>
            {opt.label}
          </SelectItem>
        ))}
      </SelectContent>
    </Select>
  );
}

/**
 * The Session Explorer: sessions sidebar + the selected session's replay
 * (header, filter toolbar, map + details, timeline dock). It fills the
 * height it is given (a flex parent): the map row takes what the docked
 * timeline leaves, and only the inner regions scroll.
 */
export function SessionExplorer({
  windowKey,
  onWindowChange,
  emptyAction,
}: Props) {
  const data = useExplorerSessions(windowKey);
  const { list, sessions, selectedId } = data;
  const scanning = !!useSessionExplorerStatus().data?.scanning;
  const [, setScopeParams] = useQueryStates(SCOPE_PARAMS);
  // A search chip opens its session at the matching event (`useSeekParam`).
  const [, setJumpAt] = useQueryState('at', parseAsInteger);
  // One sidebar: the list until a session is picked (or one is linked), then
  // only that session; "All sessions" flips back without touching the URL.
  const [sidebarMode, setSidebarMode] = useState<'list' | 'session'>(() =>
    data.selected ? 'session' : 'list'
  );
  // An external store (localStorage-backed, every access guarded) so the
  // first client render already has the persisted value; SSR renders
  // expanded via the server snapshot.
  const collapsed = useSyncExternalStore(
    subscribeSidebarCollapsed,
    getSidebarCollapsed,
    getSidebarCollapsedServer
  );
  const setCollapsed = setSidebarCollapsed;

  if (list.isLoading && !list.data)
    return (
      <div className="flex flex-col gap-3">
        <SessionExplorerSkeleton />
      </div>
    );
  if (list.isError && !list.data) {
    console.error('session explorer: session list failed', list.error);
    return (
      <div className="flex flex-col gap-3">
        <InlineError
          title="Could not load sessions"
          description="The list of recorded sessions did not load. Try again in a moment."
          onRetry={() => void list.refetch()}
        />
      </div>
    );
  }
  const windowSelect = onWindowChange ? (
    <WindowSelect windowKey={windowKey} onChange={onWindowChange} />
  ) : null;

  const showLinked = !!data.selected && !scanning;
  if (
    !sessions.length &&
    !data.debouncedSearch &&
    !list.hasNextPage &&
    !showLinked
  ) {
    // The window select lives in the sidebar, which this state replaces, so
    // it is rendered here too -- otherwise "try a longer window" would have
    // no control to act on.
    return (
      <div className="flex flex-col gap-3">
        {windowSelect ? <div className="w-48">{windowSelect}</div> : null}
        {scanning ? (
          // The first scan is still running: "none yet" would be a false
          // answer. The list fills in by itself as maps land.
          <EmptyState
            icon={<MapTrifold size={24} weight="duotone" />}
            title="Scanning your sessions…"
            description="agentplay is building maps from your coding-agent sessions. They appear here as they are ready."
          />
        ) : (
          <EmptyState
            icon={<MapTrifold size={24} weight="duotone" />}
            title="No session maps yet"
            description="Session maps appear here once a coding-agent session has been indexed. Try a longer window if you expected one."
            action={emptyAction}
          />
        )}
      </div>
    );
  }

  const listNode = (
    <SessionList
      sessions={sessions}
      selectedId={selectedId}
      // Picking a session shows its map and Details; the list stays, so
      // the next one is one click away rather than one back-out away.
      onSelect={(id) => {
        if (id !== selectedId) void setScopeParams(CLEAR_SCOPE_PARAMS);
        void data.setSelected(id);
      }}
      // Open descends into it, on every task: any task/model narrowing from
      // the previous session would otherwise follow you in.
      onOpen={(id) => {
        void setScopeParams(CLEAR_SCOPE_PARAMS);
        void data.setSelected(id);
        setSidebarMode('session');
      }}
      search={data.search}
      onSearch={(v) => void data.setSearch(v || null)}
      hasMore={!!list.hasNextPage}
      loadingMore={list.isFetchingNextPage}
      onLoadMore={() => void list.fetchNextPage()}
      unavailable={data.mapQuery.unavailable}
      onJump={(id, seq) => {
        // Always clear: a task, model or subagent scope may not contain the hit's event.
        void setScopeParams(CLEAR_SCOPE_PARAMS);
        void data.setSelected(id);
        void setJumpAt(seq);
      }}
      searchNote={
        list.data?.pages[0]?.searchNote?.code === 'arguments' ? (
          <p role="note" className="rounded-md bg-ds-warning-subtlest px-2 py-1.5 ds-text-body-xs-medium text-ds-warning-darker">
            Command arguments are never stored, so they can&rsquo;t be searched. Showing sessions that ran{' '}
            <code className="font-mono">{list.data.pages[0].searchNote.command}</code>.
          </p>
        ) : null
      }
      header={
        <SessionListHeader
          count={sessions.length}
          onCollapse={() => setCollapsed(true)}
        />
      }
      toolbar={windowSelect}
    />
  );
  const sidebar: SidebarCtl = {
    mode: sidebarMode,
    collapsed,
    setCollapsed,
    showList: () => setSidebarMode('list'),
    showSession: () => setSidebarMode('session'),
    list: listNode,
  };

  return (
    <div
      className={cn(
        'grid min-h-0 flex-1 grid-rows-[minmax(0,1fr)] gap-4',
        collapsed
          ? 'grid-cols-[40px_minmax(0,1fr)]'
          : 'grid-cols-[300px_minmax(0,1fr)]'
      )}
    >
      <ExplorerBody
        selectedId={selectedId}
        mapQuery={data.mapQuery}
        row={data.selectedRow}
        sidebar={sidebar}
      />
    </div>
  );
}

/** The sidebar column's slot: the explorer's full height, scrolling inside. */
function SidebarSlot({ children }: { children: ReactNode }) {
  return (
    <aside
      aria-label="Session explorer sidebar"
      className="h-full min-h-0 min-w-0"
    >
      {children}
    </aside>
  );
}

/** Everything right of (and including) the sidebar, by map state. */
function ExplorerBody({
  selectedId,
  mapQuery,
  row,
  sidebar,
}: {
  selectedId: string | null;
  mapQuery: MapQuery;
  row: SessionExplorerSession | null;
  sidebar: SidebarCtl;
}) {
  // Without a loaded map there is no session to show: the list (or rail).
  const listSidebar = (
    <SidebarSlot>
      {sidebar.collapsed ? (
        <SidebarRail
          label="Sessions"
          onExpand={() => sidebar.setCollapsed(false)}
        />
      ) : (
        sidebar.list
      )}
    </SidebarSlot>
  );
  // Until a map loads (and on errors) the right column is one stacked cell.
  const column = (content: ReactNode) => (
    <div className="flex min-h-0 min-w-0 flex-col gap-3">{content}</div>
  );
  if (!selectedId) {
    return (
      <>
        {listSidebar}
        {column(
          <EmptyState
            title="Pick a session"
            description="Choose a session on the left to replay its map."
          />
        )}
      </>
    );
  }
  if (mapQuery.isError) {
    console.error('session explorer: map failed', mapQuery.error);
    const copy = mapErrorCopy(mapQuery.error);
    return (
      <>
        {listSidebar}
        {column(
          <InlineError
            title={copy.title}
            description={copy.description}
            onRetry={copy.retry ? () => void mapQuery.retry() : undefined}
          />
        )}
      </>
    );
  }
  if (mapQuery.isLoading || !mapQuery.data) {
    return (
      <>
        {listSidebar}
        {column(
          <div className="grid min-h-0 min-w-0 grid-cols-[minmax(0,1fr)_300px] items-start gap-4 overflow-hidden">
            <MapSkeleton />
            <SidePanelsSkeleton />
          </div>
        )}
      </>
    );
  }
  return (
    <ErrorBoundary
      key={selectedId}
      fallback={
        <>
          {listSidebar}
          {column(
            <InlineError
              title="This session could not be displayed."
              description="Pick another session from the list."
            />
          )}
        </>
      }
    >
      <MapPlayer
        sessionId={selectedId}
        map={mapQuery.data}
        row={row}
        sidebar={sidebar}
      />
    </ErrorBoundary>
  );
}

function mapErrorCopy(error: unknown): {
  title: string;
  description: string;
  retry: boolean;
} {
  const code = error instanceof SessionExplorerError ? error.code : '';
  if (code === 'not_found') {
    return {
      title: 'Map not available',
      description:
        'This session has no stored map. Pick another session from the list.',
      retry: false,
    };
  }
  if (code === 'unsupported_schema') {
    return {
      title: 'This session map needs a newer page',
      description:
        'It was recorded in a format this page cannot draw yet. Refresh the page to pick up the latest version.',
      retry: false,
    };
  }
  return {
    title: 'Could not load this session map',
    description: 'Something went wrong fetching the map. Try again.',
    retry: true,
  };
}

/**
 * Binds the URL scope + agent lens to this session (`useExplorerScope`) and
 * remounts `MapPlayerBody` on any change (`key`), since `useReducer`'s lazy
 * playback init only runs once per mount and must re-run against the new
 * event count.
 */
function MapPlayer({
  sessionId,
  map,
  row,
  sidebar,
}: {
  sessionId: string;
  map: SessionMap;
  row: SessionExplorerSession | null;
  sidebar: SidebarCtl;
}) {
  const x = useExplorerScope(sessionId, map);
  return (
    <MapPlayerBody
      key={x.key}
      x={x}
      row={row}
      sidebar={sidebar}
    />
  );
}

/** `?at=<seq>`: a deep link to one event (e.g. from an error row or a badge).
 * Seeks the replay to the event carrying that `seq` (or that index when no
 * event carries it), then drops the param so a later seek is not undone. */
function useSeekParam(map: SessionMap, seek: (index: number) => void) {
  const [at, setAt] = useQueryState('at', parseAsInteger);
  useEffect(() => {
    if (at == null) return;
    const n = map.events.length;
    if (n) {
      // `srcSeqOf`, not `e.seq`: a task or model scope renumbers `seq`, and a
      // link (or a task's error tag) names the whole-session event.
      const bySeq = map.events.findIndex((e) => srcSeqOf(e) === at);
      seek(bySeq >= 0 ? bySeq : Math.max(0, Math.min(n - 1, at)));
    }
    void setAt(null);
  }, [at, map.events, seek, setAt]);
}

/** URL-backed sidebar tab. */
function useSideTab() {
  const [sideTab, setSideTab] = useQueryState(
    'stab',
    parseAsStringEnum<SidebarTab>([...SIDEBAR_TABS])
  );
  return { sideTab, setSideTab };
}

/** Task / model toggles, and what a click on a map node does. */
function useScopeActions(x: ExplorerScope) {
  const { setScope, lens, fullMap, setLens } = x;
  const selectTask = useCallback(
    (n: number) =>
      setScope((s0) => ({ ...s0, task: s0.task === n ? null : n })),
    [setScope]
  );
  const selectModel = useCallback(
    (m: string) =>
      setScope((s0) => ({ ...s0, model: s0.model === m ? null : m })),
    [setScope]
  );
  const onNodeAction = useCallback(
    (node: TreeNode): boolean => {
      if (node.type === 'model') {
        selectModel(node.name);
        return true;
      }
      if (node.type !== 'agent' || lens !== 'main') return false;
      const id = node.id.slice('agent:'.length);
      if (!fullMap.agents.some((a) => a.id === id)) return false;
      setLens(id);
      return true;
    },
    [selectModel, lens, fullMap.agents, setLens]
  );
  return { selectTask, selectModel, onNodeAction };
}

const REPLAY_LABEL =
  'Session replay. Space plays or pauses, arrow keys step, Shift steps 10, Home and End jump to the first and last event, E jumps to the next edit, X to the next error, D to the next delay, O to the next output, R to the next retry.';

/**
 * The fit-viewport replay: sidebar | (header with the filters on its line,
 * map + details row that takes the remaining height, timeline pinned at the
 * bottom).
 */
function MapPlayerBody({
  x,
  row,
  sidebar,
}: {
  x: ExplorerScope;
  row: SessionExplorerSession | null;
  sidebar: SidebarCtl;
}) {
  const { map, scope, sub } = x;
  const url = useSideTab();
  const cats = useEventCategories();
  const { selectTask, selectModel, onNodeAction } = useScopeActions(x);
  const scopedModels = useMemo(() => modelUsage(map), [map]);
  // Both pickers count inside the other filters: the Agent rows inside the
  // prompt/model scope, the Model rows inside the prompt.
  const agents = useMemo(
    () =>
      agentOptionsInScope(agentOptions(x.fullMap, x.ordinals), x.scopedMap),
    [x.fullMap, x.ordinals, x.scopedMap]
  );
  const pickerModels = useMemo(
    () =>
      scopedModelUsage(
        x.models,
        deriveScopeDoc(x.fullMap, { task: scope.task, model: null })
      ),
    [x.models, x.fullMap, scope.task]
  );
  const model = useMapModel(map);
  const playback = usePlaybackWindow(map);
  const { pb } = playback;
  useSeekParam(map, playback.seek);
  // A task row's error tag, or an Errors row the scope hides (`task` null when
  // that error has none: the task filter is cleared). Scope, tab and `at` change in one URL update, so the
  // replay re-scoped to the task is the one that seeks: `at` is a `seq`, which
  // survives the re-scope where an index would not. The model filter and the
  // agent lens are cleared so they can't hide the error being jumped to (the
  // Errors tab lists every agent's errors).
  const [, setAt] = useQueryState('at', parseAsInteger);
  const jumpToTaskErrors = useCallback(
    (task: number | null, seq: number) => {
      x.setScope((s0) => ({ ...s0, task, model: null }), { clearLens: true });
      void url.setSideTab('errors');
      void setAt(seq);
    },
    [x, url, setAt]
  );
  const subInfo = sub ? (x.subs.find((s) => s.id === sub) ?? null) : null;
  const hasEvents = hasReplayEvents(map);
  // The review comment whose causal path the map is lighting, as the event
  // `seq`s on that path. Owned here because the comment is clicked in the
  // right-hand column and drawn on the map beside it.
  const [reviewPath, setReviewPath] = useState<readonly number[] | null>(null);
  // How far the dock's optional lanes (Subagents / Context) grow it past
  // its budget (TimelineDock's onOverflow). The column grows by that much
  // below the fold, so the map's flex row keeps its size and the page
  // scrolls instead of shrinking it. Null until the dock first measures.
  const [dockExtra, setDockExtra] = useState<number | null>(null);
  const columnRef = useRef<HTMLDivElement>(null);
  const prevExtra = useRef<number | null>(null);
  useEffect(() => {
    if (dockExtra == null) return;
    const prev = prevExtra.current;
    prevExtra.current = dockExtra;
    // A lane was just turned on or expanded: scroll it into view. Not on
    // the first measurement, so opening a session never jumps the page.
    if (prev != null && dockExtra > prev)
      columnRef.current?.scrollIntoView({ block: 'end', behavior: 'smooth' });
  }, [dockExtra]);

  const insights = hasEvents ? (
    <InsightsPanel
      map={map}
      p={pb.p}
      ordinals={model.ordinals}
      review={model.review}
      signals={model.signals}
      onJumpSource={playback.jumpSource}
      models={scopedModels}
      model={scope.model}
      onSelectModel={selectModel}
    />
  ) : (
    <p className="ds-text-body-xs-medium text-ds-text-subtle">
      Nothing in this scope.
    </p>
  );

  return (
    <>
      <SidebarSlot>
        <ExplorerSidebar
          x={x}
          model={model}
          row={row}
          sidebar={sidebar}
          subInfo={subInfo}
          tabParam={url.sideTab}
          onTab={(t) => void url.setSideTab(t)}
          insights={insights}
          onFocusCategory={(c) => cats.setSelected(new Set([c]))}
          p={pb.p}
          onSeek={playback.seek}
          onJumpToTaskErrors={jumpToTaskErrors}
        />
      </SidebarSlot>
      <div
        ref={columnRef}
        className="flex min-h-0 min-w-0 flex-col gap-3 outline-none"
        style={
          dockExtra ? { height: `calc(100% + ${dockExtra}px)` } : undefined
        }
        onKeyDown={playback.onKeyDown}
        role="region"
        tabIndex={-1}
        aria-label={REPLAY_LABEL}
      >
        <SessionHeader
          map={map}
          row={row}
          lensLabel={x.lensLabel}
          onExitLens={() => x.setLens('main')}
          filters={
            <ExplorerToolbar
              tasks={x.tasks}
              task={scope.task}
              onTask={(task) => x.setScope((s0) => ({ ...s0, task }))}
              agents={agents}
              lens={x.lens}
              lensLabel={x.lensLabel}
              onLens={x.setLens}
              models={pickerModels}
              model={scope.model}
              onModel={(m) => x.setScope((s0) => ({ ...s0, model: m }))}
              filtered={hasScopeFilter(scope, sub)}
              onClear={x.clearAll}
            />
          }
        />
        {/* The middle row takes whatever height the docked timeline
            leaves; the map scales into it and the details column scrolls
            inside itself. */}
        <div className="grid min-h-0 min-w-0 flex-1 grid-cols-[minmax(0,1fr)_300px] grid-rows-[minmax(0,1fr)] gap-4">
          <MapPane
            map={map}
            model={model}
            p={pb.p}
            onSeek={playback.seek}
            onNodeAction={onNodeAction}
            filtered={hasScopeFilter(scope, sub)}
            filteredCopy={emptyScopeDescription(scope, sub, taskNoun(x.tasks))}
            playing={pb.playing}
            selected={cats.selected}
            path={reviewPath}
          />
          {hasEvents ? (
            <SidePanels
              map={map}
              fullMap={x.fullMap}
              p={pb.p}
              ordinals={model.ordinals}
              cumCost={model.cumCost}
              onSeek={playback.seek}
              tasks={x.tasks}
              sessionStart={x.fullMap.session.startedAt}
              task={scope.task}
              onSelectTask={selectTask}
              scoped={scope.model != null}
              selected={cats.selected}
              picks={cats.picks}
              reviewPath={reviewPath}
              onReviewPath={setReviewPath}
              inspector={
                subInfo ? (
                  <SubagentInspector
                    sub={subInfo}
                    tasks={x.tasks}
                    startedAt={x.fullMap.session.startedAt}
                  />
                ) : undefined
              }
            />
          ) : (
            <div />
          )}
        </div>
        {hasEvents ? (
          <TimelineDock
            x={x}
            playback={playback}
            model={model}
            cats={cats}
            onSelectTask={selectTask}
            subInfo={subInfo}
            collapsed={sidebar.collapsed}
            onOverflow={setDockExtra}
            columnExtra={dockExtra}
          />
        ) : null}
      </div>
    </>
  );
}