@workerdeck/ui 0.16.0 → 0.18.0

package/src/components/agent/SessionPanel.tsx

@@ -12,6 +12,7 @@ import {
   PROTOCOL_VERSION,
   mergeUsage,
   orderUsageWindows,
+  subagentLabel,
   usageInfos,
   type ModelOption,
   type PermissionMode,
@@ -54,6 +55,8 @@ import {
   type PermissionModeChoice,
 } from './PermissionModeSelect.tsx'
 import { PermissionPrompt } from './PermissionPrompt.tsx'
+import { SubagentStrip } from './SubagentStrip.tsx'
+import { subagentItems, type ToolCallItem } from '../terminal/blocks.ts'
 import { QuestionPrompt, parseUserQuestions } from './QuestionPrompt.tsx'
 import { TerminalPermissionPrompt } from '../terminal/PermissionPrompt.tsx'
 import { TerminalQuestionPrompt } from '../terminal/QuestionPrompt.tsx'
@@ -63,6 +66,8 @@ import type { TerminalAffordances } from '../terminal/affordances.tsx'
 import { SessionInfoDialog } from './SessionInfoDialog.tsx'
 import { StatusBar } from './StatusBar.tsx'
 import { Transcript } from './Transcript.tsx'
+import { ToolResultFetchProvider } from './tool-result-fetch.tsx'
+import { ToolResultImageProvider, useToolResultImages } from './tool-result-image.tsx'
 import {
   TranscriptDensityProvider,
   TranscriptVariantProvider,
@@ -227,6 +232,33 @@ export interface SessionPanelProps {
    * client's watermarks; a shared one is session metadata on the gateway).
    */
   scrubberMarks?: readonly number[]
+  /**
+   * Scroll a tool call into view; bump `nonce` to ask again for the same one.
+   * See {@link TranscriptProps.reveal} — this is the panel's pass-through, and
+   * exists so a surface *outside* the panel (a sessions list showing a session's
+   * running sub-agents) can say "take me to that one" without opening a second
+   * attach to find out where it is.
+   */
+  reveal?: { toolUseId: string; nonce: number }
+  /**
+   * Open a **sub-agent takeover**: the panel body becomes that agent's own work,
+   * with a way back. Bump `nonce` to ask again for the same one.
+   *
+   * A *request*, not a controlled value — the panel owns which agent is open,
+   * exactly as it owns `panel`. Dismissal has to work with zero host wiring
+   * (Back and Escape are the panel's own affordances), and the two hosts in
+   * scope reach this across a postMessage bridge where a controlled prop would
+   * need a live closure at the far end. Same shape and same reason as
+   * {@link SessionPanelProps.reveal}.
+   *
+   * Hosts must clear their request on a session switch: a stale one replayed at
+   * remount would open a frame the new transcript cannot answer.
+   *
+   * Claude-only in practice, and gated by data rather than by a flag — codex and
+   * provider sessions have no `parentToolUseId`, so they grow no task blocks and
+   * no sub-agent rows, and nothing can raise this.
+   */
+  openSubagent?: { toolUseId: string; nonce: number }
   /**
    * Terminal theme only: hold the prompt of the turn you are reading at the top
    * of the transcript, as the Claude Code CLI does. The **real row** is pinned
@@ -441,6 +473,8 @@ export function SessionPanel({
   terminalMetrics,
   scrubber = false,
   scrubberMarks,
+  reveal,
+  openSubagent,
   stickyPrompt = false,
   controlsSurface = 'internal',
   onControls,
@@ -464,6 +498,29 @@ export function SessionPanel({
   // is not an error channel.
   const [protocolError, setProtocolError] = useState<string | undefined>(undefined)
   const [panel, setPanel] = useState<Panel | undefined>()
+  /**
+   * The sub-agent takeover: which `Task` call the body is currently showing, or
+   * undefined for the conversation.
+   *
+   * Deliberately **not** a `Panel` member. Those route outward under
+   * `panelSurface: 'external'` so a host can draw them natively — and a host
+   * cannot draw this one: it is a transcript, and the transcript is in here. It
+   * is a mode of the conversation surface, not a screen over it.
+   */
+  const [subagentId, setSubagentId] = useState<string | undefined>(undefined)
+  /**
+   * Where to land on the way back — the row of the Task you entered from,
+   * asked for through the ordinary reveal seam.
+   *
+   * The alternative was keeping the main transcript mounted-but-hidden to
+   * preserve its scroll offset, which costs two live virtualizers and an
+   * absolute-position layout on a panel whose height just changed (the composer
+   * came back). Re-revealing is both cheaper and more honest: you return to the
+   * row you left from rather than to wherever you happened to be scrolled.
+   */
+  const [returnReveal, setReturnReveal] = useState<
+    { toolUseId: string; nonce: number } | undefined
+  >(undefined)
   const {
     state,
     connection,
@@ -479,10 +536,58 @@ export function SessionPanel({
     setModel,
     setPermissionMode,
     reconnectNow,
+    loadFullResult,
   } = useClaudeSession(client, sessionId, { onProtocolError: setProtocolError, cacheTranscript })
   // Callers are told to remount on a session switch, but a changed prop must not leave
   // the previous session's failure on screen.
   useEffect(() => setProtocolError(undefined), [sessionId])
+  // Belt to the remount contract, for the same reason: a takeover left standing
+  // across a switch would frame one session's Task id against another's items.
+  useEffect(() => {
+    setSubagentId(undefined)
+    setReturnReveal(undefined)
+  }, [sessionId])
+
+  // The host asking. Keyed on the nonce, so asking twice for the same agent
+  // works — and so a request that arrives while another frame is open swaps it
+  // in place rather than being ignored.
+  const openSubagentNonce = openSubagent?.nonce
+  const openSubagentId = openSubagent?.toolUseId
+  useEffect(() => {
+    if (openSubagentId === undefined) return
+    setSubagentId(openSubagentId)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [openSubagentNonce])
+
+  // A *reveal* asked for while framed means the reader wants the conversation:
+  // latest intent wins. Leaving the frame up and scrolling something invisible
+  // underneath it would be the worst of both.
+  const revealNonce = reveal?.nonce
+  useEffect(() => {
+    if (revealNonce === undefined) return
+    setSubagentId(undefined)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [revealNonce])
+
+  const leaveSubagent = useCallback(() => {
+    setSubagentId((current) => {
+      if (current !== undefined) setReturnReveal({ toolUseId: current, nonce: Date.now() })
+      return undefined
+    })
+  }, [])
+
+  // Escape leaves the frame — the keyboard half of Back. `defaultPrevented`
+  // keeps a dialog's own Escape (and the composer's) ahead of it: this is the
+  // outermost thing Escape can mean here, so it goes last.
+  useEffect(() => {
+    if (subagentId === undefined) return
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape' || event.defaultPrevented) return
+      leaveSubagent()
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [subagentId, leaveSubagent])
 
   // Catch-up is entered once, from the watermark the embedder handed over, and
   // left when dismissed or when the user sends anything (they are plainly
@@ -523,6 +628,29 @@ export function SessionPanel({
   // which for them never comes.
   useToolCallHost(handle, toolHost === false ? { enabled: false } : toolHost)
   const terminal = transcriptVariant === 'terminal'
+
+  // What the strip reads. The frame's items and its spawning call both come from
+  // the transcript, which is the only complete source: `SessionInfo.subagents`
+  // keeps eight settled records and is explicitly not a session's Task history.
+  const subagentFrameItems = useMemo(
+    () => (subagentId === undefined ? [] : subagentItems(state.items, subagentId)),
+    [state.items, subagentId],
+  )
+  const subagentTask = useMemo(
+    () =>
+      subagentId === undefined
+        ? undefined
+        : state.items.find(
+            (item): item is ToolCallItem => item.kind === 'tool_call' && item.id === subagentId,
+          ),
+    [state.items, subagentId],
+  )
+  // The one thing the rollup is allowed to do: name an agent whose `Task` call
+  // the transcript does not have. A label is not content.
+  const subagentFallbackLabel = useMemo(() => {
+    const record = state.session?.subagents?.find((sub) => sub.toolUseId === subagentId)
+    return record ? subagentLabel(record) : 'Sub-agent'
+  }, [state.session, subagentId])
   const capabilities = state.capabilities
 
   // Plan usage as the *gateway* knows it, merged over this session's own
@@ -630,6 +758,10 @@ export function SessionPanel({
   // path, never bytes). Stable and memoized per path: transcript rows re-render
   // on every delta, and a fresh function would re-fetch each time.
   const hostImage = useHostImage(client, sessionId, state.producedFiles)
+  // The other picture route, and the other store: an image *part* of a tool
+  // result, which an opted-in replay delivered as a reference rather than half a
+  // megabyte of base64. Bounded, unlike `useHostImage` — see the module.
+  const resultImages = useToolResultImages(client, sessionId)
   const composerRef = useRef<ComposerHandle>(null)
   // The catch-up strip's way of scrolling the (virtualized, usually unmounted)
   // recap row into view — the transcript fills it in. See TranscriptProps.
@@ -807,6 +939,12 @@ export function SessionPanel({
     // run, and they read it from this context rather than a prop chain.
     <TranscriptVariantProvider value={transcriptVariant}>
       <TranscriptDensityProvider value={transcriptDensity}>
+      {/* The panel owns the session's one attach, so it is the only thing that
+          can answer a row asking for the rest of a truncated tool result. Rows
+          rendered anywhere else fall back to the context's no-op, which is
+          correct for them: nothing truncates a replay they never asked for. */}
+      <ToolResultFetchProvider value={loadFullResult}>
+      <ToolResultImageProvider value={resultImages}>
       <div
         data-slot='session-panel'
         // The typeface is a cascade fact, not a React one — one attribute here,
@@ -828,7 +966,27 @@ export function SessionPanel({
             {protocolError}
           </Notice>
         ) : null}
+        {/* The takeover's one line: who is on screen, and the way back. Above
+            the transcript because it is a frame around it, not a row in it —
+            and because Back must be reachable without scrolling a stream that
+            is still growing. */}
+        {subagentId !== undefined ? (
+          <SubagentStrip
+            task={subagentTask}
+            items={subagentFrameItems}
+            label={subagentFallbackLabel}
+            onBack={leaveSubagent}
+            terminal={terminal}
+            fontSize={terminalMetrics?.fontSize}
+            lineHeight={terminalMetrics?.lineHeight}
+          />
+        ) : null}
         <Transcript
+          /* A remount, so the frame opens pinned to its own bottom with a fresh
+             virtualizer and height epoch — which is the right landing for both
+             cases: the live tail of a running agent, and the final report of a
+             settled one. */
+          key={subagentId ?? 'session'}
           state={state}
           fileUrl={sessionId ? (path) => client.sessionFileUrl(sessionId, path) : undefined}
           attachmentUrl={sessionId ? (id) => client.attachmentUrl(sessionId, id) : undefined}
@@ -848,6 +1006,11 @@ export function SessionPanel({
               ? { from: catchUp.itemCount, since: catchUp.since }
               : undefined
           }
+          /* On the way back, land on the Task you came from — see `returnReveal`.
+             The host's own reveal still wins when it is the newer intent. */
+          reveal={returnReveal ?? reveal}
+          frame={subagentId === undefined ? undefined : { parentToolUseId: subagentId }}
+          onOpenSubagent={setSubagentId}
           jumpToRecapRef={jumpToRecap}
           repinRef={repinTranscript}
         />
@@ -856,7 +1019,7 @@ export function SessionPanel({
             itself opens pinned to the newest row. Held with the transcript
             while the replay lands — its count is `state.items.length`, which
             during the replay is a number visibly climbing toward its answer. */}
-        {catchUp && newCount > 0 && !replaying ? (
+        {catchUp && newCount > 0 && !replaying && subagentId === undefined ? (
           <div className='px-3 pb-1'>
             <div
               data-slot='catch-up'
@@ -934,7 +1097,17 @@ export function SessionPanel({
             </PromptSurface>
           </div>
         ) : null}
-        {readOnly ? null : (
+        {/* No composer while a sub-agent is framed: you cannot talk to one, and a
+            live-looking input that silently addresses its *parent* is worse than
+            no input at all. Its interrupt goes with it — Back is one press away,
+            and a second interrupt control would be a second thing that stops
+            something the reader is not looking at.
+
+            The approval prompts above deliberately do NOT go with it. A
+            sub-agent's own tool calls raise session-level permission requests,
+            so hiding them here would let the takeover deadlock the very agent it
+            is showing until the reader happened to press Back. */}
+        {readOnly || subagentId !== undefined ? null : (
         <Composer
           ref={composerRef}
           onSend={handleSend}
@@ -1009,6 +1182,8 @@ export function SessionPanel({
           </>
         ) : null}
       </div>
+      </ToolResultImageProvider>
+      </ToolResultFetchProvider>
       </TranscriptDensityProvider>
     </TranscriptVariantProvider>
   )

package/src/components/agent/SessionSteps.tsx

@@ -0,0 +1,233 @@
+import {
+  ArrowRight,
+  Check,
+  ChevronDown,
+  ChevronRight,
+  CircleAlert,
+  Dot,
+  PauseCircle,
+} from 'lucide-react'
+import { isAgentRecord, subagentLabel } from '@workerdeck/protocol'
+import type { SessionInfo, SubagentInfo } from '@workerdeck/protocol'
+import { Spinner } from '../ui/Spinner.tsx'
+import { cn } from '../../lib/utils.ts'
+
+/**
+ * The work *under* a session row, and the one row shape every client renders it
+ * through.
+ *
+ * This lived inside the VS Code webview first, which is exactly why the
+ * dashboard had none of it. Nothing in here is extension-specific: a session's
+ * sub-agents are a protocol fact, and a disclosure over them is a list
+ * affordance. It sits in `packages/ui` so the sidebar, the dashboard and (in its
+ * own idiom) the phone are annotating rows the same way rather than three ways.
+ *
+ * Today the only source is `SessionInfo.subagents`. The other — the CLI's own
+ * **task checklist**, the to-do list it keeps for the current turn — is what the
+ * design was drawn from, and it is not built: nothing on the wire carries it yet
+ * (see `_docs/features/sub-agent-handling.md`, second thread, which opens with
+ * "check a capture" rather than "design a surface"). When it arrives it is a
+ * *source*, not a second row component: checklist when the session has one, its
+ * sub-agents otherwise.
+ *
+ * That is also why `state` has a `pending` arm no sub-agent can produce. A
+ * sub-agent record exists only once dispatched, so it is never queued; a to-do
+ * is queued for most of its life, and dropping the state would mean widening the
+ * union later — the shape is cheaper to state now than to retrofit.
+ */
+export type Step = {
+  key: string
+  label: string
+  /** What one of these is called, for the disclosure's count. */
+  noun: string
+  /**
+   * An **agent** has an identity and work of its own, so it is pressable and
+   * wears the sub-agent colour. A **task** is something the model described with
+   * no agent behind it (`isAgentRecord`), so it is inert: there is no frame to
+   * open, and a row that offered one would show an empty screen.
+   *
+   * Two values and not a boolean because the checklist source this shape was
+   * drawn for (see above) produces the second kind natively — a to-do is a task
+   * in exactly this sense, and it will slot in here rather than widening
+   * anything.
+   */
+  kind: 'agent' | 'task'
+  state: 'done' | 'running' | 'pending' | 'failed'
+  /** A trailing reading — a sub-agent's tool count. Absent draws nothing. */
+  detail?: string
+  title: string
+  onSelect: () => void
+}
+
+export function sessionSteps(
+  info: SessionInfo,
+  onSelectSubagent: (toolUseId: string) => void,
+): Step[] {
+  // The label is protocol's `subagentLabel`, not a spelling of its own: the
+  // dashboard and the phone render the same rows from the same records, and two
+  // spellings would be two different answers to "which agent is this".
+  return (info.subagents ?? []).map((sub) => ({
+    key: sub.toolUseId,
+    label: subagentLabel(sub),
+    noun: 'agent',
+    kind: isAgentRecord(sub) ? ('agent' as const) : ('task' as const),
+    state: stepState(sub.status),
+    detail: sub.toolCount > 0 ? String(sub.toolCount) : undefined,
+    title: `${subagentLabel(sub)} · ${sub.toolCount} tool${sub.toolCount === 1 ? '' : 's'}`,
+    onSelect: () => onSelectSubagent(sub.toolUseId),
+  }))
+}
+
+function stepState(status: SubagentInfo['status']): Step['state'] {
+  switch (status) {
+    case 'running':
+      return 'running'
+    case 'failed':
+      return 'failed'
+    default:
+      return 'done'
+  }
+}
+
+/** How many of these are still going — the live half of the disclosure's count. */
+export function runningSteps(steps: readonly Step[]): number {
+  return steps.filter((s) => s.state === 'running').length
+}
+
+/**
+ * The disclosure, which is also the reading: `3 agents` — or `2 of 3 agents`
+ * while some have settled, because "how many are still going" is the live
+ * question and a bare total answers it wrong the moment one finishes.
+ *
+ * Sub-agents are an annotation on a working row rather than a state of their own
+ * (see `runningSubagents` in protocol's `session-list.ts`), so this never
+ * competes with the row's status glyph: that still says what the *session* is
+ * doing.
+ */
+export function StepToggle({
+  expanded,
+  running,
+  total,
+  noun,
+  onToggle,
+}: {
+  expanded: boolean
+  running: number
+  total: number
+  noun: string
+  onToggle: () => void
+}) {
+  // Two spellings of one count. The **words** are the honest reading and go in
+  // the tooltip and to a screen reader; the line itself gets the digits, because
+  // this sits on the second line of a 280px row next to the folder and the age,
+  // and `1 of 6 agents` truncated the folder name away to say something the row
+  // could say in three characters.
+  const label = running > 0 && running < total ? `${running}/${total}` : String(total)
+  const words =
+    running > 0 && running < total
+      ? `${running} of ${total} ${noun}s running`
+      : `${total} ${noun}${total === 1 ? '' : 's'}`
+  const Chevron = expanded ? ChevronDown : ChevronRight
+  return (
+    <button
+      type='button'
+      aria-expanded={expanded}
+      aria-label={`${expanded ? 'Hide' : 'Show'} ${words}`}
+      title={`${expanded ? 'Hide' : 'Show'} ${words}`}
+      onClick={(e) => {
+        // The whole row is a button and this one does not mean "select" — the
+        // same guard the row's overflow needs, and the reason a drag-select
+        // inside the row does not toggle it.
+        e.stopPropagation()
+        onToggle()
+      }}
+      className={cn(
+        'flex shrink-0 items-center gap-0.5 rounded px-0.5 outline-none',
+        'hover:bg-surface-hover hover:text-fg-2',
+        running > 0 ? 'text-info' : 'text-fg-4',
+      )}>
+      <Chevron className='size-3' />
+      <span className='tabular-nums'>{label}</span>
+    </button>
+  )
+}
+
+/**
+ * One step under its session. Pressing an **agent** hands the panel over to that
+ * agent's own work — it is not a session and never becomes one, but it does now
+ * have a surface (`SessionPanel.openSubagent`). A host that cannot frame one
+ * falls back to revealing its `Task` row, which was this row's only meaning
+ * before the takeover existed. A **task** is not pressable at all; see
+ * {@link Step.kind}.
+ *
+ * Divided from the row's header and from each other by a rule rather than by
+ * indentation: these are a list *inside* the row, and at 11px an indent is not
+ * enough to say so. The rule is black at 25% so it darkens whatever the row is
+ * filled with, selected or not, without needing a colour per state.
+ */
+export function StepRow({ step, onSelect }: { step: Step; onSelect: () => void }) {
+  const agent = step.kind === 'agent'
+  // Body colour by *kind*, state carried by the icon — the rule the transcript's
+  // own `TaskRow` already follows, where the body is green and the marker holds
+  // the beat. Green means sub-agent across this product (it is the one hue
+  // nothing else on a session surface claims), so a list that spent blue on
+  // "running" here would be saying something different from the transcript
+  // about the same agent. Failure still outranks it: an alarm is not a category.
+  const body = step.state === 'failed' ? 'text-danger' : agent ? 'text-success' : 'text-fg-4'
+  const content = (
+    <>
+      <StepIcon state={step.state} kind={step.kind} />
+      <span className='min-w-0 flex-1 truncate'>{step.label}</span>
+      {/* The progress reading while it works, and what it cost when it is done.
+          Zero draws nothing: `0 tools` beside a thinking agent reads as a stall,
+          which is the same call `taskSummary` makes one surface over. */}
+      {step.detail ? <span className='shrink-0 tabular-nums text-fg-4'>{step.detail}</span> : null}
+      {agent ? <ArrowRight className='size-3 shrink-0 opacity-60' /> : null}
+    </>
+  )
+  const shape =
+    'flex w-full items-center gap-2 border-t border-black/25 py-1 pl-3 pr-2 text-left text-label outline-none'
+
+  // A task is not a button, in the markup and not merely in the styling: there
+  // is nothing to press, and a disabled-looking button still announces itself as
+  // one. It stops the click all the same — the whole session row is pressable
+  // underneath, so falling through would open the session from a row that says
+  // it does nothing.
+  if (!agent) {
+    return (
+      <div title={step.title} onClick={(e) => e.stopPropagation()} className={cn(shape, body)}>
+        {content}
+      </div>
+    )
+  }
+  return (
+    <button
+      type='button'
+      title={step.title}
+      onClick={(e) => {
+        e.stopPropagation()
+        onSelect()
+      }}
+      className={cn(shape, 'hover:bg-surface-hover', body)}>
+      {content}
+    </button>
+  )
+}
+
+function StepIcon({ state, kind }: { state: Step['state']; kind: Step['kind'] }) {
+  // A task that is neither running nor failed gets a neutral dot rather than a
+  // tick: `done` is a claim about work, and nothing here did any.
+  if (kind === 'task' && state !== 'running' && state !== 'failed') {
+    return <Dot className='size-3 shrink-0' />
+  }
+  switch (state) {
+    case 'running':
+      return <Spinner className='size-3 shrink-0' />
+    case 'failed':
+      return <CircleAlert className='size-3 shrink-0' />
+    case 'pending':
+      return <PauseCircle className='size-3 shrink-0' />
+    default:
+      return <Check className='size-3 shrink-0' />
+  }
+}

package/src/components/agent/SessionWorkspace.tsx

@@ -41,6 +41,8 @@ export interface SessionWorkspaceProps {
   scrubberMarks?: SessionPanelProps['scrubberMarks']
   /** The last prompt pinned above the transcript — see `SessionPanel`. */
   stickyPrompt?: SessionPanelProps['stickyPrompt']
+  /** Take the panel body over with one sub-agent's work — see `SessionPanel`. */
+  openSubagent?: SessionPanelProps['openSubagent']
   /** Which end of the panel the status bar sits at — see `SessionPanel`. */
   statusPlacement?: SessionPanelProps['statusPlacement']
   controlsSurface?: SessionPanelProps['controlsSurface']
@@ -103,6 +105,7 @@ export function SessionWorkspace({
   scrubber,
   scrubberMarks,
   stickyPrompt,
+  openSubagent,
   statusPlacement,
   controlsSurface,
   unseen,
@@ -307,6 +310,7 @@ export function SessionWorkspace({
           scrubber={scrubber}
           scrubberMarks={scrubberMarks}
           stickyPrompt={stickyPrompt}
+          openSubagent={openSubagent}
           controlsSurface={controlsSurface}
           statusPlacement={statusPlacement}
           unseen={unseen}

package/src/components/agent/StatusBar.tsx

@@ -8,6 +8,7 @@ import { Spinner } from '../ui/Spinner.tsx'
 import { Tip } from '../ui/Tooltip.tsx'
 import { cn } from '../../lib/utils.ts'
 import { formatCost, formatCountdown, formatTokens } from '../../lib/format.ts'
+import { meterColorClass } from '../../lib/status.ts'
 import { STATUS_META } from './status.ts'
 import { useTranscriptVariant } from './transcript-variant.tsx'
 
@@ -63,8 +64,9 @@ function useNow(intervalMs = 30_000): number {
   return now
 }
 
-const utilizationColor = (pct: number) =>
-  pct >= 95 ? 'text-danger' : pct >= 80 ? 'text-warning' : 'text-fg-3'
+/** The shared ramp, aliased for the two call sites below — the thresholds live
+ * in `lib/status.ts` beside the severity they mirror. */
+const utilizationColor = (pct: number) => meterColorClass(pct)
 
 /** The CLI reports category colors as its own theme token names ('inactive',
  * 'promptBorder', ...), not CSS colors — only pass through what CSS can render. */