@workerdeck/ui 0.17.0 → 0.19.0

package/src/components/agent/SessionBrowser.tsx

@@ -1,4 +1,5 @@
 import { useEffect, useMemo, useRef, useState } from 'react'
+import type { ReactNode } from 'react'
 import {
   BellRing,
   CircleAlert,
@@ -21,6 +22,7 @@ import {
   groupRows,
   hasFacetFilter,
   projectLabel,
+  projectSubpath,
   projectsOf,
   sessionLabel,
   subsetSummary,
@@ -38,7 +40,10 @@ import { Empty } from '../ui/Empty.tsx'
 import { Input } from '../ui/Input.tsx'
 import { Select, SelectContent, SelectItem, SelectItemText, SelectTrigger, SelectValue } from '../ui/Select.tsx'
 import { Spinner } from '../ui/Spinner.tsx'
+import { ContextRing } from './ContextRing.tsx'
+import { EngineIcon, vendorMarkClass, vendorTextClass } from './EngineIcon.tsx'
 import { ProjectIcon } from './ProjectIcon.tsx'
+import { StepRow, StepToggle, runningSteps, sessionSteps } from './SessionSteps.tsx'
 import { cn } from '../../lib/utils.ts'
 import { formatCost, formatRelativeTime, friendlyModel } from '../../lib/format.ts'
 
@@ -77,6 +82,10 @@ export interface SessionBrowserProps {
    * double-click would have already left the page.
    */
   onRename?: (row: SessionRow, title: string) => void
+  /** Open a session *at* one of its sub-agents, when the host can scroll a
+   * transcript to a `Task` row. Absent, the sub-agent list still expands and a
+   * step just opens its session — see `SessionRowItemProps`. */
+  onSelectSubagent?: (row: SessionRow, toolUseId: string) => void
   /** Rendered when nothing at all exists (as opposed to nothing matching). */
   emptyState?: React.ReactNode
   /**
@@ -135,6 +144,7 @@ export function SessionBrowser({
   onSelect,
   onDelete,
   onRename,
+  onSelectSubagent,
   emptyState,
   showControls = true,
   projectIcons,
@@ -298,12 +308,13 @@ export function SessionBrowser({
                   key={`${row.hostId}:${row.info.id}`}
                   row={row}
                   active={row.info.id === activeId}
-                  showGateway={gateways.length > 1}
+                  showGateway={gateways.length > 1 && config.groupBy !== 'gateway'}
                   showProject={config.groupBy !== 'project'}
                   projectIcons={projectIcons}
                   onSelect={onSelect}
                   onDelete={onDelete}
                   onRename={onRename}
+                  onSelectSubagent={onSelectSubagent}
                 />
               ))}
             </div>
@@ -329,15 +340,25 @@ interface SessionRowItemProps {
   row: SessionRow
   active?: boolean
   showGateway?: boolean
-  /** False when the list is already grouped by project — the header has said
-   * the name, so the slot goes back to the cwd's basename, which inside a
-   * project group is the one thing the header cannot say. The rule `showGateway`
+  /** False when the list is already grouped by project — the header has said the
+   * name, so the row must not spend its metadata line repeating it. What takes
+   * the slot is the *sub-path inside the project* (`projectSubpath`), which is
+   * the one thing the header cannot say and the only thing that tells two
+   * sessions in the same repo apart; a session sitting at the project root has
+   * nothing to add and the slot disappears entirely. The rule `showGateway`
    * follows one facet over. */
   showProject?: boolean
   projectIcons?: Record<string, string>
   onSelect?: (row: SessionRow) => void
   onDelete?: (row: SessionRow) => void
   onRename?: (row: SessionRow, title: string) => void
+  /** Open one of a session's sub-agents — which now means handing the session
+   * panel over to that agent's own work (`SessionPanel.openSubagent`), and meant
+   * "scroll to its `Task` row" before that surface existed. Both are honest; a
+   * host picks what it can draw. Optional, and its absence is not a missing
+   * feature: without it a step just opens the session, which is all a host with
+   * neither can offer. Only *agent* steps ever call it — see `Step.kind`. */
+  onSelectSubagent?: (row: SessionRow, toolUseId: string) => void
 }
 
 function SessionRowItem({
@@ -349,30 +370,41 @@ function SessionRowItem({
   onSelect,
   onDelete,
   onRename,
+  onSelectSubagent,
 }: SessionRowItemProps) {
   const { info } = row
   const [editing, setEditing] = useState(false)
+  // Expansion is the row's own state and deliberately not persisted: a list that
+  // reopened yesterday's work on every reload would be showing a settled tail
+  // nobody asked for.
+  const [expanded, setExpanded] = useState(false)
 
   // What it is and what it has spent, in one line — the same set the extension
   // shows, joined the same way, so the two lists read as one product.
-  const folder = info.cwd.split('/').filter(Boolean).pop() ?? info.cwd
   // protocol's own spelling, so this row, the group header above it and the
-  // project facet cannot disagree about what a project is called. It falls back
-  // to exactly the basename this line drew before the feature existed.
-  const project = showProject ? projectLabel(row) : folder
+  // project facet cannot disagree about what a project is called. Under a
+  // project group it is the sub-path instead — see `showProject` — and a session
+  // at the root contributes nothing at all rather than a name already on screen.
+  const project = showProject ? projectLabel(row) : projectSubpath(row)
   const projectIcon = showProject ? info.project?.icon : undefined
+  const engine = info.engine ?? 'claude'
+  // Everything after the model. The model itself is drawn separately because it
+  // is the one segment that wears a colour — see `vendorTextClass` — and a
+  // coloured run inside a joined string would have to be spliced back out.
   const details = [
-    showGateway ? row.hostName : undefined,
-    friendlyModel(info.model),
     project,
+    showGateway ? row.hostName : undefined,
     info.profile ? `@${info.profile}` : undefined,
     formatCost(info.totalCostUsd),
   ].filter(Boolean)
+  const steps = sessionSteps(info, (toolUseId) =>
+    onSelectSubagent ? onSelectSubagent(row, toolUseId) : onSelect?.(row),
+  )
   // Where the icon goes: immediately before the project's own name, wherever
   // that landed in the joined line. Split rather than interleaved as nodes,
   // because everything here is one truncating mono run and a flex of pieces
   // would each shrink a little and leave several half-words.
-  const cut = details.indexOf(project)
+  const cut = project === undefined ? -1 : details.indexOf(project)
 
   return (
     <div
@@ -390,9 +422,20 @@ function SessionRowItem({
         'group flex cursor-pointer flex-col gap-0.5 text-left transition-colors',
         rowShapeClass(active === true),
       )}>
-      {/* Line one: what you scan the list by on the left, how it is doing on the
-          right, state last. */}
+      {/* Line one: how it is doing, then what you scan the list by, then how
+          long since it moved.
+
+          State leads. It used to sit last, on the argument that the title is
+          what you read and the state is what you glance at — but a glance wants
+          a *column*, and a trailing glyph has no fixed x: it lands wherever the
+          age and the ring leave it. Leading, every row's state stacks into one
+          scannable strip, and the mark on line two lands under it in the same
+          gutter. This is the VS Code sidebar's shape, and all three clients are
+          on it now. */}
       <div className='flex items-center gap-1.5'>
+        <Gutter>
+          <SessionStatusIcon row={row} />
+        </Gutter>
         {/* The editor replaces the link rather than sitting inside it — an
             input nested in a button is invalid, and disabling the button to
             protect the edit disables the field with it. */}
@@ -427,16 +470,33 @@ function SessionRowItem({
         <span className='shrink-0 text-label text-fg-4'>
           {formatRelativeTime(info.lastActivityAt ?? info.createdAt)}
         </span>
-        <SessionStatusIcon row={row} />
+        <ContextRing usage={info.contextUsage} />
       </div>
 
-      {/* Line two: what it is, with the actions at the far right — away from the
-          state icon, and away from the title you are actually reading. */}
+      {/* Line two: what it is — the engine's mark and its model in the vendor's
+          own colour, then where it runs — with the actions at the far right,
+          away from the title you are actually reading. */}
       <div className='flex items-center gap-1 text-label text-fg-4'>
+        <Gutter>
+          {/* The colour goes on the icon, not on this cell: the svg ships its
+              own `text-fg-3` and only a class on the element itself merges over
+              it. */}
+          <EngineIcon
+            engine={engine}
+            model={info.model}
+            className={vendorMarkClass(engine, info.model)}
+          />
+        </Gutter>
         <button
           type='button'
           tabIndex={-1}
           className='min-w-0 flex-1 truncate text-left font-mono outline-none'>
+          <span className={vendorTextClass(engine, info.model)}>
+            {/* The model id as a person says it — `claude-opus-5[1m]` is a wire
+                value, and a list line has no room for a context-window suffix. */}
+            {friendlyModel(info.model)}
+          </span>
+          {details.length > 0 ? ' · ' : ''}
           {cut < 0 ? (
             details.join(' · ')
           ) : (
@@ -454,6 +514,15 @@ function SessionRowItem({
             </>
           )}
         </button>
+        {steps.length > 0 ? (
+          <StepToggle
+            expanded={expanded}
+            running={runningSteps(steps)}
+            total={steps.length}
+            noun={steps[0]!.noun}
+            onToggle={() => setExpanded((v) => !v)}
+          />
+        ) : null}
         {onRename && !editing ? (
           <Button
             variant='ghost'
@@ -481,22 +550,46 @@ function SessionRowItem({
           </Button>
         ) : null}
       </div>
+      {expanded ? steps.map((step) => <StepRow key={step.key} step={step} onSelect={step.onSelect} />) : null}
     </div>
   )
 }
 
 /**
- * State as one glyph on the right edge — a ringing bell when it wants a human, a
- * spinner while it works, a moon when it is only sleeping. Replaces the text
- * badge: in a sidebar the word costs more room than it earns, and the states
- * that matter are the two you can recognise without reading.
+ * The one 14px cell both lines hang their glyph in.
+ *
+ * A shared column rather than a leading character: the state and the engine mark
+ * are different widths and a bare glyph would let the two text columns start at
+ * different x. Centring inside a fixed cell is what makes them agree —
+ * `packages/ui`'s terminal-gutter argument at row scale.
+ */
+function Gutter({ children }: { children: ReactNode }) {
+  return <span className='flex w-3.5 shrink-0 items-center justify-center'>{children}</span>
+}
+
+/**
+ * State as one glyph — a ringing bell when it wants a human, a spinner while it
+ * works, a moon when it is only sleeping. Replaces the text badge: in a sidebar
+ * the word costs more room than it earns, and the states that matter are the two
+ * you can recognise without reading.
+ *
+ * **It reads `row.state`, not `info.status`, and that distinction is the whole
+ * point of the row model.** `sessionState` already folds in the arm this glyph
+ * cannot see for itself: a *background* sub-agent outlives its turn by design, so
+ * the turn ends, `status` comes to rest at `idle`, and the agent keeps working.
+ * Reading the raw status drew a **moon on a row filed under the "Working"
+ * header** — the list contradicting itself on one line, which is exactly what a
+ * derived view model exists to prevent. The value was in scope and unread.
+ *
+ * The terminal statuses still come off `info.status`, because `ended` collapses
+ * `failed` and `closed` into one bucket and those are worth telling apart here.
  */
 export function SessionStatusIcon({ row }: { row: SessionRow }) {
   const { info } = row
-  if (info.pendingPermissionCount > 0 || info.status === 'awaiting_approval') {
+  if (row.state === 'attention') {
     return <BellRing className='size-3.5 shrink-0 animate-pulse text-warning' />
   }
-  if (info.status === 'running' || info.status === 'starting') {
+  if (row.state === 'working') {
     return <Spinner className='size-3.5 shrink-0 text-info' />
   }
   switch (info.status) {

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'
@@ -237,6 +240,25 @@ export interface SessionPanelProps {
    * 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
@@ -452,6 +474,7 @@ export function SessionPanel({
   scrubber = false,
   scrubberMarks,
   reveal,
+  openSubagent,
   stickyPrompt = false,
   controlsSurface = 'internal',
   onControls,
@@ -475,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,
@@ -495,6 +541,53 @@ export function SessionPanel({
   // 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
@@ -535,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
@@ -850,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}
@@ -870,7 +1006,11 @@ export function SessionPanel({
               ? { from: catchUp.itemCount, since: catchUp.since }
               : undefined
           }
-          reveal={reveal}
+          /* 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}
         />
@@ -879,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'
@@ -957,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}