:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { useActions, useValues } from 'kea'
import { type ReactNode, memo, useCallback, useEffect, useMemo, useRef, useState } from 'react'
import { cn } from 'lib/utils/css-classes'
import { inStorybookTestRunner } from 'lib/utils/dom'
import { isTerminalRunStatus, runStreamLogic } from '../logics/runStreamLogic'
import { ReasoningAnswer } from '../messages/ReasoningAnswer'
import type { ThreadItem, ToolInvocation } from '../types/streamTypes'
import {
groupThreadActivity,
groupToolRuns,
isRunningStatus,
isStartupStatus,
reuseActivityGroups,
type ThreadActivityGroup as ThreadActivityGroupItem,
type ThreadDisplayItem,
} from '../utils/groupThreadActivity'
import { getRandomThinkingMessage } from '../utils/thinkingMessages'
import { resolveToolCall } from '../utils/toolResolver'
import { TurnHoverStore } from '../utils/turnHoverStore'
import { type TurnTrailer, computeTurnTrailers, mapRowsToRevealGroup } from '../utils/turnTrailers'
import { ContextUsageChip } from './ContextUsageChip'
import { PullRequestCard } from './PullRequestCard'
import { type ThreadSkin, ThreadSkinContext } from './quill/quillThreadContext'
import { RunAlertActivity } from './RunAlertActivity'
import { RunContext } from './RunContext'
import { ThreadActivityGroup } from './ThreadActivityGroup'
import { ThreadRow, type ThreadRowProps } from './ThreadRow'
import { lookupToolRenderer } from './tool/toolRegistry'
import { TurnReveal } from './TurnReveal'
import { VirtualizedThread } from './VirtualizedThread'
/** Stable row key — defined at module scope so `getItemKey` never changes identity across renders. */
function getThreadRowKey(row: ThreadViewRow): string {
return row.item.id
}
/**
* Typical rendered height per item type (px, gap excluded). These seed the virtualizer before a row is
* first measured; the closer they sit to reality, the less the scroll position has to be corrected while
* scrolling up through unvisited rows — which is what reads as drag/jumping. Rough is fine, order of
* magnitude matters: a collapsed tool card is ~2 lines, a markdown message is a paragraph or more.
*/
const THREAD_ITEM_HEIGHT_ESTIMATES: Partial<Record<ThreadItem['type'], number>> = {
human_message: 160,
assistant_message: 46,
assistant_thought: 26,
tool_invocation: 42,
turn_separator: 24,
error: 42,
status: 42,
compact_boundary: 42,
conversation_cleared: 42,
task_notification: 26,
progress: 42,
debug: 30,
}
/** The quill thread leaves a lone call or thought outside a group, and such a row shows its own live state. */
function quillRowShowsProgress(item: ThreadDisplayItem, toolInvocations: ReadonlyMap<string, ToolInvocation>): boolean {
switch (item.type) {
case 'assistant_thought':
// An empty thought renders nothing, so the bottom indicator still has to show.
return !!item.text?.trim()
case 'tool_invocation': {
const status = item.toolCallId ? toolInvocations.get(item.toolCallId)?.status : undefined
return status === 'pending' || status === 'in_progress'
}
case 'status':
return isStartupStatus(item) || isRunningStatus(item)
default:
return false
}
}
function estimateThreadRowHeight({ item }: ThreadViewRow): number {
if (item.type === 'activity_group') {
return 48
}
return THREAD_ITEM_HEIGHT_ESTIMATES[item.type] ?? 56
}
interface ThreadViewProps {
scrollRestorationKey?: string
/**
* Pass `false` when an ancestor already owns scroll (the live Max column + auto-scroller) — rows then
* render in document flow, unchanged from the pre-virtualized layout. Defaults to virtualized.
*/
virtualized?: boolean
/**
* Opts the context-usage line into the footer, shown only between turns (when the agent isn't actively
* working). Off by default so a bare `ThreadView` is unaffected; the run surface turns it on for live,
* non-scout runs.
*/
showContextUsage?: boolean
/** Renders per-turn UI (e.g. feedback actions) at each completed turn's end. */
renderTurnTrailer?: (trailer: TurnTrailer) => JSX.Element | null
/** Extra footer content below the thinking / PR / context-usage rows (e.g. the feedback prompt). */
footerExtra?: ReactNode
className?: string
listClassName?: string
endInset?: number
rowClassName?: string
/**
* `quill` lays the thread out like PostHog Desktop's chat: user bubbles, ghost assistant prose, and
* each step as a quill chat marker. Every presenter below picks its skin from `ThreadSkinContext`,
* so tool renderers need no changes.
*/
skin?: ThreadSkin
}
const QUILL_ROW_GAP = 16
/**
* Sandbox-runtime thread presenter. Reads `runStreamLogic.values.threadItems` (assistant text,
* tool-invocation references, run separators, inline errors) from whatever `runStreamLogic`
* instance is bound above it — a live PostHog AI conversation or a read-only run viewer — and
* dispatches tool cards through the sandbox tool registry. Conversation-agnostic by design: it knows
* only the bound stream logic, never langgraph vs sandbox or the conversation.
*
* Rows are virtualized through `VirtualizedThread`, which owns scroll and stick-to-bottom; the leading
* run context and trailing thinking indicator / PR card / context-usage line ride along as the
* header/footer rows.
*/
export function ThreadView({
scrollRestorationKey,
virtualized = true,
showContextUsage = false,
renderTurnTrailer,
footerExtra,
className,
listClassName,
rowClassName,
endInset,
skin = 'lemon',
}: ThreadViewProps): JSX.Element {
const {
threadItems,
toolInvocations,
isThinking,
streamPhase,
showThinkingIndicator,
runArtifacts,
turnComplete,
currentRunStatus,
contextUsage,
runConnectionState,
logBootstrapLoading,
pendingPermissionRequest,
olderHistoryState,
historyTurnBase,
} = useValues(runStreamLogic)
const { loadOlderHistory } = useActions(runStreamLogic)
const turnCancelled = currentRunStatus === 'cancelled'
// A replayed error from an earlier run in the chain is not this run's ending while a newer run is
// still going, so it keeps the softer title.
const runEnded = isTerminalRunStatus(currentRunStatus)
const { pinnedToolIds, widgetToolIds } = useMemo(() => {
const pinned = new Set<string>()
const widgets = new Set<string>()
for (const [id, invocation] of toolInvocations) {
const resolved = resolveToolCall(invocation)
const entry = lookupToolRenderer(resolved.resolvedKey, !!resolved.innerToolName)
if (entry.pinned) {
pinned.add(id)
} else if (entry.keepVisible) {
widgets.add(id)
}
}
return { pinnedToolIds: pinned, widgetToolIds: widgets }
}, [toolInvocations])
const previousDisplayItems = useRef<ThreadDisplayItem[]>([])
const displayItems = useMemo(() => {
const grouped =
skin === 'quill'
? groupToolRuns(threadItems, toolInvocations, { pinnedToolIds, widgetToolIds, settled: !isThinking })
: groupThreadActivity(threadItems, new Set([...pinnedToolIds, ...widgetToolIds]))
const reconciled = reuseActivityGroups(previousDisplayItems.current, grouped)
previousDisplayItems.current = reconciled
return reconciled
}, [threadItems, toolInvocations, pinnedToolIds, widgetToolIds, skin, isThinking])
// The last human message anchors the thread. Reopening a saved conversation lands on it — the last
// meaningful turn, response below — when at least a viewport of content follows it (otherwise the
// bottom); a fresh send (a new key) pins the thread to the bottom to follow the streaming response.
const anchorItemKey = useMemo(
() => threadItems.findLast((item) => item.type === 'human_message')?.id ?? null,
[threadItems]
)
// Only computed when a trailer renderer is supplied — bare ThreadViews pay nothing.
const previousTrailers = useRef<Map<string, TurnTrailer> | null>(null)
const trailers = useMemo(() => {
const next = renderTurnTrailer
? reuseTurnTrailers(previousTrailers.current, computeTurnTrailers(threadItems, historyTurnBase))
: null
previousTrailers.current = next
return next
}, [threadItems, renderTurnTrailer, historyTurnBase])
const revealGroups = useMemo(() => mapRowsToRevealGroup(displayItems), [displayItems])
const previousRows = useRef<ThreadViewRow[]>([])
const rows = useMemo(() => {
const next = buildThreadViewRows(previousRows.current, displayItems, toolInvocations, trailers, revealGroups)
previousRows.current = next
return next
}, [displayItems, toolInvocations, trailers, revealGroups])
const [turnHoverStore] = useState(() => new TurnHoverStore())
// Header/footer are kept as memoized leaf components with stable element identity so they don't rebuild
// `VirtualizedThread`'s `renderRow` (and re-sweep visible rows) on every streamed frame. Each is wrapped
// in `VirtualizedThread.Row` like the item rows so it gets virtualized positioning + height measurement.
const { branch, baseBranch, repo } = runArtifacts
const header = useMemo(
() =>
branch ? (
<VirtualizedThread.Row className={rowClassName}>
<ThreadHeader branch={branch} baseBranch={baseBranch} repo={repo} />
</VirtualizedThread.Row>
) : undefined,
[branch, baseBranch, repo, rowClassName]
)
// The connection banner (reconnecting / connection-failed) owns the footer line when present, so it
// takes precedence over the thinking indicator (a mid-run reconnect otherwise reads as normal thinking).
const showConnectionStatus = !!runConnectionState
const lastItem = displayItems.at(-1)
const lastRowShowsProgress =
lastItem?.type === 'activity_group' ||
(skin === 'quill' && !!lastItem && quillRowShowsProgress(lastItem, toolInvocations))
const showThinking =
showThinkingIndicator && !showConnectionStatus && !pendingPermissionRequest && !lastRowShowsProgress
const thinkingPhase = streamPhase === 'provisioning' ? 'provisioning' : 'thinking'
// Post-turn only: a reconnect refetch can fold in a pr_url mid-run, so gate on !isThinking.
const pullRequestUrl = !isThinking ? runArtifacts.prUrl : undefined
// Context usage rides the thread footer, but only between turns (idle) — never while the agent is
// working, where the thinking line takes the footer. `ContextUsageChip` self-hides without data.
const showContextUsageFooter = showContextUsage && streamPhase === 'idle' && !!contextUsage
const footer = useMemo(
() =>
showThinking || pullRequestUrl || showContextUsageFooter || showConnectionStatus || footerExtra ? (
<VirtualizedThread.Row className={rowClassName}>
<ThreadFooter
showThinking={showThinking}
thinkingPhase={thinkingPhase}
pullRequestUrl={pullRequestUrl}
prBranch={branch}
showContextUsage={showContextUsageFooter}
showConnectionStatus={showConnectionStatus}
extra={footerExtra}
/>
</VirtualizedThread.Row>
) : undefined,
[
showThinking,
thinkingPhase,
pullRequestUrl,
branch,
showContextUsageFooter,
showConnectionStatus,
footerExtra,
rowClassName,
]
)
const renderItem = useCallback(
({ item, isLast, turnId, invocation, groupInvocations, trailer }: ThreadViewRow): JSX.Element => {
if (item.type === 'activity_group') {
return (
<ActivityGroupRow
group={item}
rowClassName={rowClassName}
turnHoverStore={turnHoverStore}
turnId={turnId}
toolInvocations={groupInvocations ?? EMPTY_INVOCATIONS}
active={isLast && isThinking}
waitingForInput={isLast && !!pendingPermissionRequest}
cancelled={isLast && (turnCancelled || currentRunStatus === 'failed')}
turnComplete={turnComplete}
turnCancelled={turnCancelled}
/>
)
}
if (item.type === 'turn_separator' && renderTurnTrailer) {
return (
<TurnTrailerRow
turnId={item.id}
trailer={trailer}
renderTurnTrailer={renderTurnTrailer}
rowClassName={rowClassName}
turnHoverStore={turnHoverStore}
/>
)
}
return (
<ItemRow
item={item}
rowClassName={rowClassName}
turnHoverStore={turnHoverStore}
turnId={turnId}
isLast={isLast}
isThinking={isThinking}
invocation={invocation}
turnComplete={turnComplete}
turnCancelled={turnCancelled}
runEnded={runEnded}
/>
)
},
[
isThinking,
turnComplete,
turnCancelled,
rowClassName,
renderTurnTrailer,
turnHoverStore,
pendingPermissionRequest,
currentRunStatus,
runEnded,
]
)
const thread = (
<VirtualizedThread.Root
key={scrollRestorationKey}
scrollRestorationKey={scrollRestorationKey}
items={rows}
getItemKey={getThreadRowKey}
estimateItemHeight={estimateThreadRowHeight}
anchorItemKey={anchorItemKey}
// The history replay folds in over several commits (debug rows land before the human turns);
// the opening scroll must wait for the full log or it opens at the bottom of a partial thread.
itemsLoading={logBootstrapLoading}
onNearTop={olderHistoryState === 'idle' ? loadOlderHistory : undefined}
header={header}
footer={footer}
stickToBottom
// Provisioning counts too: the optimistic "spinning up" window is part of the turn, so the
// thread is already pinned when the first streamed rows land.
turnActive={streamPhase !== 'idle'}
virtualized={virtualized}
endInset={endInset}
gap={skin === 'quill' ? QUILL_ROW_GAP : undefined}
className={className}
listClassName={listClassName}
>
{renderItem}
</VirtualizedThread.Root>
)
if (skin === 'lemon') {
return thread
}
return (
<ThreadSkinContext.Provider value={skin}>
{/* Virtualized, the root lays out rows itself; in document flow, this wrapper sets the rhythm. */}
{/* Quill's text color, set once here: a ghost bubble sets none, so its prose would inherit the page's. */}
<div
data-quill
className={cn('text-[var(--foreground)]', virtualized ? 'contents' : 'flex flex-col gap-4')}
>
{thread}
</div>
</ThreadSkinContext.Provider>
)
}
function reuseTurnTrailers(
previous: Map<string, TurnTrailer> | null,
next: Map<string, TurnTrailer>
): Map<string, TurnTrailer> {
if (!previous) {
return next
}
for (const [id, trailer] of next) {
const old = previous.get(id)
if (
old &&
old.turnIndex === trailer.turnIndex &&
old.isLastTurn === trailer.isLastTurn &&
old.turnText === trailer.turnText &&
old.traceId === trailer.traceId &&
old.timestamp === trailer.timestamp
) {
next.set(id, old)
}
}
return next
}
const EMPTY_INVOCATIONS: Map<string, ToolInvocation> = new Map()
interface ThreadViewRow {
item: ThreadDisplayItem
isLast: boolean
turnId?: string
invocation?: ToolInvocation
groupInvocations?: Map<string, ToolInvocation>
trailer?: TurnTrailer
}
function sameInvocations(a: Map<string, ToolInvocation> | undefined, b: Map<string, ToolInvocation>): boolean {
if (!a || a.size !== b.size) {
return false
}
for (const [id, invocation] of b) {
if (a.get(id) !== invocation) {
return false
}
}
return true
}
function buildThreadViewRows(
previous: ThreadViewRow[],
displayItems: ThreadDisplayItem[],
toolInvocations: Map<string, ToolInvocation>,
trailers: Map<string, TurnTrailer> | null,
revealGroups: Map<string, string>
): ThreadViewRow[] {
const previousById = new Map<string, ThreadViewRow>()
for (const row of previous) {
previousById.set(row.item.id, row)
}
return displayItems.map((item, index) => {
const old = previousById.get(item.id)
let groupInvocations: Map<string, ToolInvocation> | undefined
if (item.type === 'activity_group') {
groupInvocations = new Map()
for (const activity of item.items) {
const call = activity.toolCallId ? toolInvocations.get(activity.toolCallId) : undefined
if (call) {
groupInvocations.set(activity.toolCallId!, call)
}
}
if (sameInvocations(old?.groupInvocations, groupInvocations)) {
groupInvocations = old!.groupInvocations
}
}
const row: ThreadViewRow = {
item,
isLast: index === displayItems.length - 1,
turnId: revealGroups.get(item.id),
invocation:
item.type !== 'activity_group' && item.toolCallId ? toolInvocations.get(item.toolCallId) : undefined,
groupInvocations,
trailer: trailers?.get(item.id),
}
return old &&
old.item === row.item &&
old.isLast === row.isLast &&
old.turnId === row.turnId &&
old.invocation === row.invocation &&
old.groupInvocations === row.groupInvocations &&
old.trailer === row.trailer
? old
: row
})
}
interface RowShellProps {
rowClassName?: string
turnHoverStore: TurnHoverStore
}
const ActivityGroupRow = memo(function ActivityGroupRow({
group,
rowClassName,
turnHoverStore,
turnId,
toolInvocations,
active,
waitingForInput,
cancelled,
turnComplete,
turnCancelled,
}: RowShellProps & {
group: ThreadActivityGroupItem
turnId: string | undefined
toolInvocations: Map<string, ToolInvocation>
active: boolean
waitingForInput: boolean
cancelled: boolean
turnComplete: boolean
turnCancelled: boolean
}): JSX.Element {
const renderGroupItem = useCallback(
(activity: ThreadItem): JSX.Element => (
<ThreadRow
item={activity}
isLast={false}
isThinking={false}
invocation={activity.toolCallId ? toolInvocations.get(activity.toolCallId) : undefined}
turnComplete={turnComplete}
turnCancelled={turnCancelled}
/>
),
[toolInvocations, turnComplete, turnCancelled]
)
return (
<VirtualizedThread.Row className={rowClassName}>
<TurnReveal store={turnHoverStore} turnId={turnId}>
<ThreadActivityGroup
group={group}
toolInvocations={toolInvocations}
active={active}
waitingForInput={waitingForInput}
cancelled={cancelled}
renderItem={renderGroupItem}
/>
</TurnReveal>
</VirtualizedThread.Row>
)
})
const TurnTrailerRow = memo(function TurnTrailerRow({
turnId,
trailer,
renderTurnTrailer,
rowClassName,
turnHoverStore,
}: RowShellProps & {
turnId: string
trailer: TurnTrailer | undefined
renderTurnTrailer: (trailer: TurnTrailer) => JSX.Element | null
}): JSX.Element {
return (
<VirtualizedThread.Row className={rowClassName}>
{trailer ? (
<TurnReveal store={turnHoverStore} turnId={turnId}>
{renderTurnTrailer(trailer)}
</TurnReveal>
) : null}
</VirtualizedThread.Row>
)
})
const ItemRow = memo(function ItemRow({
item,
rowClassName,
turnHoverStore,
turnId,
...rowProps
}: RowShellProps & Omit<ThreadRowProps, 'item'> & { item: ThreadItem; turnId: string | undefined }): JSX.Element {
return (
<VirtualizedThread.Row className={rowClassName}>
<TurnReveal store={turnHoverStore} turnId={turnId}>
<ThreadRow item={item} {...rowProps} />
</TurnReveal>
</VirtualizedThread.Row>
)
})
/** Leading run-context row. Memoized so it only re-renders when the run's branch/repo refs change. */
const ThreadHeader = memo(function ThreadHeader({
branch,
baseBranch,
repo,
}: {
branch: string
baseBranch?: string
repo?: string
}): JSX.Element {
return <RunContext branch={branch} baseBranch={baseBranch} repo={repo} />
})
/**
* Trailing row: the "what's it doing now" thinking line, the produced PR card, and/or the context-usage
* line (between turns). Subscribes to `currentProgress` itself so the frequently-updating progress text
* stays isolated here — it never re-renders `ThreadView` or destabilizes the footer's element identity
* during streaming.
*/
const ThreadFooter = memo(function ThreadFooter({
showThinking,
thinkingPhase,
pullRequestUrl,
prBranch,
showContextUsage,
showConnectionStatus,
extra,
}: {
showThinking: boolean
thinkingPhase: 'thinking' | 'provisioning'
pullRequestUrl?: string
prBranch?: string
showContextUsage?: boolean
showConnectionStatus?: boolean
extra?: ReactNode
}): JSX.Element {
// `runConnectionState` is self-subscribed here (like `currentProgress`) so the frequently-updating
// reconnect attempt counter stays isolated to this leaf and never destabilizes `ThreadView`'s footer.
const { currentProgress, runConnectionState } = useValues(runStreamLogic)
const { retryConnection } = useActions(runStreamLogic)
// `gap-1.5` matches the thread's inter-row gap (`VirtualizedThread`'s `gap` default) so stacked footer
// items keep the same vertical rhythm as the thread.
return (
<div className="flex flex-col gap-1.5">
{showConnectionStatus && runConnectionState && (
<RunAlertActivity {...runConnectionState} onRetry={retryConnection} />
)}
{showThinking && (
<ThinkingIndicator
progress={thinkingPhase === 'provisioning' ? null : currentProgress}
phase={thinkingPhase}
/>
)}
{pullRequestUrl && <PullRequestCard prUrl={pullRequestUrl} branch={prBranch} />}
{showContextUsage && <ContextUsageChip />}
{extra}
</div>
)
})
/**
* Bottom-of-thread "what's it doing right now" line for sandbox conversations. Reflects the latest
* `_posthog/progress` message when present; during `provisioning` (the conversations/open POST / cold
* boot before `run_started`) it shows a fixed "spinning up" message, otherwise the canned thinking rotation.
*/
function ThinkingIndicator({
progress,
phase,
}: {
progress: string | null
phase: 'thinking' | 'provisioning'
}): JSX.Element {
const [fallbackMessage, setFallbackMessage] = useState(() => getRandomThinkingMessage())
// Re-roll the gerund every 5s while genuinely thinking; static "Spinning up sandbox…" during provisioning
// doesn't need it, and rotating in Storybook would make snapshots non-deterministic.
useEffect(() => {
if (phase !== 'thinking' || inStorybookTestRunner()) {
return
}
const interval = setInterval(() => setFallbackMessage(getRandomThinkingMessage()), 5000)
return () => clearInterval(interval)
}, [phase])
const message = progress?.trim() ? progress : phase === 'provisioning' ? 'Setting up sandbox' : fallbackMessage
// Match the LangGraph loader: a bubble-free reasoning line (muted brain icon + muted text), via the
// shared Activity primitive — not a MessageTemplate bubble. Shimmers only while genuinely thinking;
// provisioning stays static since it's infra boot, not model reasoning.
return (
<ReasoningAnswer
content={message}
id="sandbox-thinking"
completed={false}
showCompletionIcon={false}
animate={phase === 'thinking' || phase === 'provisioning'}
/>
)
}