feat(agents): context-usage breakdown popover (system / tools / messages / free)

Hovering the usage indicator now reveals a per-part composition of the prompt,
modelled on Claude Code's `/context`: a stacked bar + legend showing how much
of the window the system prompt, tool definitions, conversation messages, and
free space each occupy.

The runtime persists an approximate decomposition of the stable request parts:
pi-adapter estimates `{ system, tools }` token cost (char/4 via approxTokens)
once per call and writes it to the step as `context_breakdown` alongside the
cache-inclusive `context_input_tokens`. The UI derives the "messages" bucket as
the real total minus those estimates, so the segments always sum to the gauge
even though the part figures are approximate. New shared helpers
`computeContextBreakdown` / `parseContextBreakdown` in token-accountant keep the
math testable and out of the component.

- entity-schema: additive `context_breakdown` string column on steps.
- outbound-bridge / pi-adapter: compute + persist the estimate.
- token-accountant: breakdown helpers + types, exported from the client entry.
- UI: HoverCard popover (ContextUsageDetails) with a composition bar + legend.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: kevin-dp

packages/agents-runtime/src/client.ts

@@ -50,13 +50,18 @@ export {
   CONTEXT_USAGE_BACKGROUND_START,
   CONTEXT_USAGE_HARD_CEILING,
   computeContextUsage,
+  computeContextBreakdown,
+  parseContextBreakdown,
   contextUsageLevel,
   formatContextUsagePercent,
 } from './token-accountant'
 export type {
   ContextUsage,
   ContextUsageInput,
   ContextUsageLevel,
+  ContextBreakdownKey,
+  ContextBreakdownParts,
+  ContextBreakdownSegment,
 } from './token-accountant'
 export type { GoalCommand } from './goal-command'
 

packages/agents-runtime/src/entity-schema.ts

@@ -176,6 +176,12 @@ type StepValue = {
   // the usage so consumers can render a fraction without resolving the model
   // registry themselves.
   context_window?: number
+  // JSON-encoded estimate of how the prompt decomposes across the stable
+  // request parts — `{ system, tools }` token counts (approximate; char/4).
+  // The UI derives the remaining "messages" bucket as the real cache-inclusive
+  // total minus these, so the breakdown always sums to the gauge. Optional and
+  // additive; older events without it stay valid.
+  context_breakdown?: string
 }
 type TextValue = {
   key?: string
@@ -533,6 +539,7 @@ function createStepSchema(): Schema<StepValue> {
     duration_ms: z.number().int().optional(),
     input_tokens: z.number().int().nonnegative().optional(),
     output_tokens: z.number().int().nonnegative().optional(),
+    context_breakdown: z.string().optional(),
   })
 }
 

packages/agents-runtime/src/outbound-bridge.ts

@@ -163,6 +163,9 @@ export interface OutboundBridge {
     // Model context window for this step, persisted as `context_window`.
     contextWindow?: number
     durationMs?: number
+    // Approx token decomposition of the stable request parts (system + tools),
+    // persisted as `context_breakdown` for the usage-details popover.
+    tokenBreakdown?: { system: number; tools: number }
   }) => void
   onTextStart: () => void
   onTextDelta: (delta: string) => void
@@ -332,6 +335,8 @@ export function createOutboundBridge(
       tokenContext?: number
       contextWindow?: number
       durationMs?: number
+      /** Approximate token decomposition of the stable request parts. */
+      tokenBreakdown?: { system: number; tools: number }
     }) {
       if (!currentStepKey) return
       writeEvent(
@@ -357,6 +362,9 @@ export function createOutboundBridge(
             ...(opts?.contextWindow !== undefined && {
               context_window: opts.contextWindow,
             }),
+            ...(opts?.tokenBreakdown !== undefined && {
+              context_breakdown: JSON.stringify(opts.tokenBreakdown),
+            }),
           } as never,
         }) as ChangeEvent
       )

packages/agents-runtime/src/pi-adapter.ts

@@ -314,6 +314,15 @@ export function createPiAgentAdapter(
     const modelContextWindow =
       typeof model.contextWindow === `number` ? model.contextWindow : 0
 
+    // Approximate token cost of the stable, non-message request parts. These
+    // are constant for the whole call, so estimate once and persist on each
+    // step; the UI derives the "messages" bucket as the real cache-inclusive
+    // total minus these (see token-accountant computeContextBreakdown).
+    const tokenBreakdown = {
+      system: approxTokens(opts.systemPrompt),
+      tools: approxTokens(opts.tools),
+    }
+
     const transformContext =
       opts.onCompactContext && modelContextWindow > 0
         ? async (
@@ -617,6 +626,7 @@ export function createPiAgentAdapter(
                     tokenContext: usageContext,
                   }),
                   ...(contextWindow !== undefined && { contextWindow }),
+                  tokenBreakdown,
                 })
 
                 if (isError) {

packages/agents-runtime/src/token-accountant.ts

@@ -75,6 +75,80 @@ export function computeContextUsage(
   return { usedTokens, contextWindow: input.contextWindow, ratio }
 }
 
+export type ContextBreakdownKey = `system` | `tools` | `messages` | `free`
+
+export interface ContextBreakdownSegment {
+  key: ContextBreakdownKey
+  label: string
+  tokens: number
+  /** Fraction of the whole context window, [0, 1]. */
+  ratio: number
+}
+
+/** Estimated token cost of the stable request parts (from `context_breakdown`). */
+export interface ContextBreakdownParts {
+  systemTokens?: number
+  toolsTokens?: number
+}
+
+const CONTEXT_BREAKDOWN_LABELS: Record<ContextBreakdownKey, string> = {
+  system: `System prompt`,
+  tools: `Tools`,
+  messages: `Messages`,
+  free: `Free space`,
+}
+
+/**
+ * Decompose a step's context usage into display segments: the *estimated*
+ * stable parts (system prompt + tools, char/4 approximations persisted on the
+ * step) plus the real "messages" remainder and the free space. The used
+ * segments (everything but `free`) sum to `usage.usedTokens` and all four sum
+ * to the window — so the breakdown always agrees with the gauge even though the
+ * part estimates are approximate. Modelled on Claude Code's `/context` view.
+ */
+export function computeContextBreakdown(
+  usage: ContextUsage,
+  parts: ContextBreakdownParts = {}
+): Array<ContextBreakdownSegment> {
+  const window = usage.contextWindow
+  const used = Math.max(0, Math.min(usage.usedTokens, window))
+  const system = Math.max(0, Math.min(parts.systemTokens ?? 0, used))
+  const tools = Math.max(0, Math.min(parts.toolsTokens ?? 0, used - system))
+  const messages = Math.max(0, used - system - tools)
+  const free = Math.max(0, window - used)
+  const segment = (
+    key: ContextBreakdownKey,
+    tokens: number
+  ): ContextBreakdownSegment => ({
+    key,
+    label: CONTEXT_BREAKDOWN_LABELS[key],
+    tokens,
+    ratio: window > 0 ? tokens / window : 0,
+  })
+  return [
+    segment(`system`, system),
+    segment(`tools`, tools),
+    segment(`messages`, messages),
+    segment(`free`, free),
+  ]
+}
+
+/** Parse the persisted `context_breakdown` JSON into estimate parts (tolerant). */
+export function parseContextBreakdown(
+  raw: string | undefined | null
+): ContextBreakdownParts {
+  if (!raw) return {}
+  try {
+    const obj = JSON.parse(raw) as { system?: unknown; tools?: unknown }
+    return {
+      ...(typeof obj.system === `number` && { systemTokens: obj.system }),
+      ...(typeof obj.tools === `number` && { toolsTokens: obj.tools }),
+    }
+  } catch {
+    return {}
+  }
+}
+
 export type ContextUsageLevel = `normal` | `warning` | `critical`
 
 /**

packages/agents-runtime/test/token-accountant.test.ts

@@ -3,6 +3,8 @@ import {
   CONTEXT_USAGE_BACKGROUND_START,
   CONTEXT_USAGE_HARD_CEILING,
   computeContextUsage,
+  computeContextBreakdown,
+  parseContextBreakdown,
   contextUsageLevel,
   formatContextUsagePercent,
   formatContextBudgetNotice,
@@ -13,6 +15,52 @@ import {
 } from '../src/token-accountant'
 import type { LLMMessage } from '../src/types'
 
+describe(`computeContextBreakdown`, () => {
+  const usage = { usedTokens: 50_000, contextWindow: 100_000, ratio: 0.5 }
+
+  it(`splits into system / tools / messages / free that sum to the window`, () => {
+    const segs = computeContextBreakdown(usage, {
+      systemTokens: 5_000,
+      toolsTokens: 15_000,
+    })
+    expect(segs.map((s) => [s.key, s.tokens])).toEqual([
+      [`system`, 5_000],
+      [`tools`, 15_000],
+      [`messages`, 30_000], // used (50k) − system − tools
+      [`free`, 50_000], // window − used
+    ])
+    // Used segments sum to usedTokens; all four sum to the window.
+    expect(segs.slice(0, 3).reduce((n, s) => n + s.tokens, 0)).toBe(50_000)
+    expect(segs.reduce((n, s) => n + s.tokens, 0)).toBe(100_000)
+    expect(segs[2].ratio).toBeCloseTo(0.3)
+  })
+
+  it(`defaults missing parts to zero (messages absorbs the whole used total)`, () => {
+    const segs = computeContextBreakdown(usage)
+    expect(segs.find((s) => s.key === `messages`)?.tokens).toBe(50_000)
+    expect(segs.find((s) => s.key === `system`)?.tokens).toBe(0)
+  })
+
+  it(`never produces negative messages when estimates exceed the real total`, () => {
+    const segs = computeContextBreakdown(
+      { usedTokens: 1_000, contextWindow: 100_000, ratio: 0.01 },
+      { systemTokens: 5_000, toolsTokens: 15_000 }
+    )
+    // System is capped at used; tools/messages can't go below zero.
+    expect(segs.find((s) => s.key === `messages`)?.tokens).toBe(0)
+    expect(segs.every((s) => s.tokens >= 0)).toBe(true)
+  })
+
+  it(`parseContextBreakdown reads persisted JSON and tolerates junk`, () => {
+    expect(parseContextBreakdown(`{"system":12,"tools":34}`)).toEqual({
+      systemTokens: 12,
+      toolsTokens: 34,
+    })
+    expect(parseContextBreakdown(undefined)).toEqual({})
+    expect(parseContextBreakdown(`not json`)).toEqual({})
+  })
+})
+
 describe(`computeContextUsage`, () => {
   it(`sums input + output against the window`, () => {
     const usage = computeContextUsage({

packages/agents-server-ui/src/components/ContextUsageDetails.module.css

@@ -0,0 +1,113 @@
+.panel {
+  min-width: 230px;
+  max-width: 280px;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  font-variant-numeric: tabular-nums;
+}
+
+.header {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 0.5rem;
+}
+
+.title {
+  font-size: 0.8rem;
+  font-weight: 600;
+  color: var(--text, inherit);
+}
+
+.headline {
+  font-size: 0.8rem;
+  font-weight: 600;
+  color: var(--text, inherit);
+}
+
+.subhead {
+  font-size: 0.72rem;
+  color: var(--text-muted, rgba(0, 0, 0, 0.55));
+  margin-top: -0.25rem;
+}
+
+/* Stacked composition bar. */
+.bar {
+  display: flex;
+  width: 100%;
+  height: 8px;
+  border-radius: 4px;
+  overflow: hidden;
+  background: var(--surface-sunken, rgba(0, 0, 0, 0.06));
+}
+
+.barSeg {
+  height: 100%;
+  display: block;
+}
+
+.legend {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.legendRow {
+  display: grid;
+  grid-template-columns: 0.6rem 1fr auto auto;
+  align-items: center;
+  gap: 0.4rem;
+  font-size: 0.72rem;
+}
+
+.swatch {
+  width: 0.6rem;
+  height: 0.6rem;
+  border-radius: 2px;
+  flex-shrink: 0;
+}
+
+.legendLabel {
+  color: var(--text, inherit);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.legendTokens {
+  color: var(--text-muted, rgba(0, 0, 0, 0.55));
+  text-align: right;
+}
+
+.legendPercent {
+  color: var(--text-muted, rgba(0, 0, 0, 0.55));
+  text-align: right;
+  min-width: 2.4rem;
+}
+
+.note {
+  font-size: 0.66rem;
+  color: var(--text-muted, rgba(0, 0, 0, 0.45));
+  font-style: italic;
+}
+
+/* Per-segment colours, shared by the bar fills and the legend swatches. */
+.system {
+  background: var(--accent-9, #4c6ef5);
+}
+
+.tools {
+  background: var(--violet-9, #7048e8);
+}
+
+.messages {
+  background: var(--teal-9, #0ca678);
+}
+
+.free {
+  background: var(--surface-sunken, rgba(0, 0, 0, 0.12));
+}