@workerdeck/ui 0.16.0 → 0.18.0

package/src/components/agent/tool-result-fetch.tsx

@@ -0,0 +1,36 @@
+import { createContext, useContext, type ReactNode } from 'react'
+
+/**
+ * How a row gets back the part of a tool result the replay did not send.
+ *
+ * A **context**, not a prop chain, for the same reason the variant is one: the
+ * rows that need it are drawn by `terminalBlocks` and by the cards theme's
+ * `ToolCallCard`, several layers below whoever holds the session, and a row
+ * composed by hand should get the same behaviour without threading a callback
+ * through everything in between.
+ *
+ * The default is a no-op resolving `false`, which is exactly right for every
+ * surface that never asked for truncation (the playground, a fixture, an
+ * embedder rendering rows by hand): `result.truncated` is only ever set by a
+ * replay a renderer opted into, so a row that has no fetcher also has no head to
+ * complete. A press still opens the row; it simply has everything already.
+ */
+export type ToolResultFetcher = (toolUseId: string) => Promise<boolean>
+
+const FetchContext = createContext<ToolResultFetcher>(async () => false)
+
+export function ToolResultFetchProvider({
+  value,
+  children,
+}: {
+  value: ToolResultFetcher | undefined
+  children: ReactNode
+}) {
+  return <FetchContext.Provider value={value ?? noop}>{children}</FetchContext.Provider>
+}
+
+const noop: ToolResultFetcher = async () => false
+
+export function useToolResultFetcher(): ToolResultFetcher {
+  return useContext(FetchContext)
+}

package/src/components/agent/tool-result-image.tsx

@@ -0,0 +1,209 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react'
+import type { WorkerDeckClient } from '@workerdeck/client'
+
+/**
+ * How a row gets the picture the replay refused to send.
+ *
+ * The sibling of `tool-result-fetch.tsx` and the same shape of seam, because it
+ * answers the same shape of question: an opted-in socket delivers a base64
+ * `image` part as an `image_ref` — media type, decoded size, and its index in
+ * the stored block — and the bytes are fetched over REST by whoever is actually
+ * looking at the row. Across a measured corpus that payload was 91% of every
+ * tool result and nothing rendered a byte of it.
+ *
+ * A **context**, not a prop chain, for the variant's reason: the rows are drawn
+ * by `terminalBlocks` and by `ToolCallCard`, several layers under whoever holds
+ * the session. The default resolves `undefined`, which is exactly right for
+ * every surface that never asked (the playground, a fixture, a hand-composed
+ * row): `result.images` is only ever set by a replay a renderer opted into, so a
+ * row with no loader also has no reference to load. Only `SessionPanel` supplies
+ * a real one, because it owns the session's one attach and therefore the only
+ * `(seq, toolUseId)` addresses that mean anything.
+ */
+
+/** One image part, as the row addresses it: the reducer's entry plus the id of
+ * the call it came back from. `sourceSeq` is the entry's **own** — the
+ * result-level one is cleared by text hydration, and a reader who pressed "show
+ * everything" must still be able to load the screenshot afterwards. */
+export type ToolResultImageRef = {
+  toolUseId: string
+  sourceSeq: number
+  partIndex: number
+  mediaType: string
+  bytes: number
+}
+
+/** Resolves an object URL for the picture, or `undefined` when the gateway will
+ * not serve it — a stale address after a dormant wake, a gateway with no such
+ * route, a dropped connection. The row draws a box either way. */
+export type ToolResultImageLoader = (ref: ToolResultImageRef) => Promise<string | undefined>
+
+const noop: ToolResultImageLoader = async () => undefined
+
+const ImageContext = createContext<ToolResultImageLoader>(noop)
+
+export function ToolResultImageProvider({
+  value,
+  children,
+}: {
+  value: ToolResultImageLoader | undefined
+  children: ReactNode
+}) {
+  return <ImageContext.Provider value={value ?? noop}>{children}</ImageContext.Provider>
+}
+
+export function useToolResultImageLoader(): ToolResultImageLoader {
+  return useContext(ImageContext)
+}
+
+/**
+ * Long enough that a fast scrub through an image-heavy session fetches nothing
+ * it flew past, short enough to be invisible to a reader who stopped.
+ *
+ * There is no second visibility system here on purpose: the transcript is
+ * virtualized, so a *mounted* row is by definition within an overscan of the
+ * viewport — the virtualizer already is the IntersectionObserver, and a second
+ * answer to a question that has one is how the two disagree.
+ */
+const MOUNT_SETTLE_MS = 150
+
+export type ToolResultImageState = { src?: string; failed: boolean }
+
+/**
+ * One box's load, for either theme.
+ *
+ * Fires once the row has been mounted for {@link MOUNT_SETTLE_MS}, and then
+ * **runs to completion** — an aborted fetch re-pays the whole image on the
+ * return visit, and the gateway is HTTP/1.1, so the browser's per-origin
+ * connection cap is the concurrency throttle for free.
+ *
+ * The effect keys on the address's *primitives*, never on the ref object: the
+ * reducer replaces items on every streamed delta, so an object-identity dep
+ * would re-run this on every token of the turn after it.
+ */
+export function useToolResultImageSrc(ref: ToolResultImageRef): ToolResultImageState {
+  const load = useToolResultImageLoader()
+  const [state, setState] = useState<ToolResultImageState>({ failed: false })
+  const { toolUseId, sourceSeq, partIndex, mediaType, bytes } = ref
+  useEffect(() => {
+    let live = true
+    setState({ failed: false })
+    const timer = setTimeout(() => {
+      load({ toolUseId, sourceSeq, partIndex, mediaType, bytes })
+        .then((src) => {
+          if (live) setState({ src, failed: src === undefined })
+        })
+        .catch(() => {
+          if (live) setState({ failed: true })
+        })
+    }, MOUNT_SETTLE_MS)
+    return () => {
+      live = false
+      clearTimeout(timer)
+    }
+  }, [load, toolUseId, sourceSeq, partIndex, mediaType, bytes])
+  return state
+}
+
+/** ~64 MB of decoded pictures held at once. At the corpus's 335 KB median that
+ * is ~190 images, which no viewport holds; the budget exists so a session
+ * scrolled end to end does not pin every screenshot it passed. */
+const CACHE_BUDGET_BYTES = 64 * 1024 * 1024
+
+type Entry = { pending: Promise<string | undefined>; url?: string; bytes: number }
+
+/**
+ * `useHostImage`'s shape, generalized to the replay route — and **bounded**,
+ * which `useHostImage` is not.
+ *
+ * The promise-per-key cache is what makes this callable from a transcript row at
+ * all: rows re-render on every streamed delta, and an uncached resolver would
+ * re-fetch each time. The LRU is the part that is new. Object URLs pin their
+ * blob until revoked, so a fully-scrolled hundred-image session would otherwise
+ * hold ~50 MB until the panel unmounted — and evicting means revoking, or the
+ * eviction frees a `Map` entry and nothing else.
+ *
+ * Re-fetching on a return scroll is fine, and is the whole design: the bytes are
+ * one authenticated request away, which is precisely what makes it cheap not to
+ * have shipped them in the attach.
+ */
+export function useToolResultImages(
+  client: WorkerDeckClient,
+  sessionId: string | undefined,
+): ToolResultImageLoader {
+  const cache = useRef(new Map<string, Entry>())
+  useEffect(
+    () => () => {
+      for (const entry of cache.current.values()) if (entry.url) URL.revokeObjectURL(entry.url)
+      cache.current.clear()
+    },
+    [],
+  )
+  return useCallback(
+    (ref: ToolResultImageRef) => {
+      if (!sessionId) return Promise.resolve(undefined)
+      // The whole address, because every part of it can change under a row that
+      // is still on screen: a dormant wake restarts the seqs, and a cached
+      // address that outlived its log must miss rather than serve another
+      // call's pixels.
+      const key = `${sessionId}:${ref.sourceSeq}:${ref.toolUseId}:${ref.partIndex}`
+      const hit = cache.current.get(key)
+      if (hit) {
+        // Re-inserting is the "recently used" half of the LRU: `Map` iterates in
+        // insertion order, so eviction reads oldest-first for free.
+        cache.current.delete(key)
+        cache.current.set(key, hit)
+        return hit.pending
+      }
+      // Fetched rather than pointed at: a bare `<img src>` at the gateway
+      // carries a credential in exactly one of four clients (the dashboard's
+      // same-origin host), and a broken icon in the other three.
+      const pending = client
+        .toolResultImage(sessionId, ref.sourceSeq, ref.toolUseId, ref.partIndex)
+        .then((blob) => {
+          if (blob.size === 0) return undefined
+          const url = URL.createObjectURL(blob)
+          const entry = cache.current.get(key)
+          if (entry) {
+            entry.url = url
+            entry.bytes = blob.size
+            evict(cache.current, key)
+          } else {
+            // Evicted (or unmounted) while in flight — nothing will ever draw
+            // this, and an unrevoked URL is the leak the budget exists to stop.
+            URL.revokeObjectURL(url)
+          }
+          return url
+        })
+        .catch(() => undefined)
+      // The declared size is what the budget counts until the bytes land: a
+      // hundred fetches in flight must not all read as free.
+      cache.current.set(key, { pending, bytes: ref.bytes })
+      return pending
+    },
+    [client, sessionId],
+  )
+}
+
+/** Drop oldest-first until the held bytes fit the budget, revoking as it goes.
+ * `keep` is the entry just resolved — evicting the picture a row is about to
+ * draw would be a fetch spent on nothing. */
+function evict(cache: Map<string, Entry>, keep: string): void {
+  let held = 0
+  for (const entry of cache.values()) held += entry.bytes
+  for (const [key, entry] of cache) {
+    if (held <= CACHE_BUDGET_BYTES) return
+    if (key === keep) continue
+    if (entry.url) URL.revokeObjectURL(entry.url)
+    cache.delete(key)
+    held -= entry.bytes
+  }
+}

package/src/components/agent/transcript-rows.ts

@@ -7,20 +7,31 @@
 import type { TranscriptItem } from '@workerdeck/react'
 import { needsBlank, type TerminalBlock } from '../terminal/items.tsx'
 
-/** One row of the virtual list: a {@link TerminalBlock} (a transcript item, or
- * — under the terminal theme — a folded run of tool calls), or the recap
- * boundary line spliced in at `catchUp.from`. One flat array so the virtualizer
- * sees stable indices, and each row carries the key the item was already
- * React-keyed by — measurements are cached per key, so a row keeps its measured
- * height when the recap splice shifts every index after it. */
-export type TranscriptRow = TerminalBlock | { key: 'recap'; line: string }
+/** One row of the virtual list: a {@link TerminalBlock} (a transcript item,
+ * — under the terminal theme — a folded run of tool calls, or a task block
+ * standing for a `Task` call and everything its subagent produced), or the
+ * recap boundary line spliced in at `catchUp.from`. One flat array so the
+ * virtualizer sees stable indices, and each row carries the key the item was
+ * already React-keyed by — measurements are cached per key, so a row keeps its
+ * measured height when the recap splice shifts every index after it. */
+export type TranscriptRow =
+  | TerminalBlock
+  | { key: 'recap'; line: string }
+  /** The sub-agent's brief, spliced in as the takeover frame's first row — what
+   * the agent was asked, before what it did. Synthetic like the recap row and
+   * for the same reason: it is not a transcript item (the engine puts the
+   * instruction in the spawning call's `prompt`, never in the stream), but it
+   * has to be a row so the virtualizer can size and key it. */
+  | { key: 'brief'; text: string }
 
-/** The item a row is spaced *as*. A run stands for the calls it folded, so a
- * run and a lone tool call below it still read as one block. */
+/** The item a row is spaced *as*. A run stands for the calls it folded, and a
+ * task block for the `Task` call it absorbed into — all tool calls, so a run,
+ * a task and a lone tool call below them still read as one block. */
 export function rowItem(row: TranscriptRow | undefined): TranscriptItem | undefined {
   if (!row) return undefined
   if ('item' in row) return row.item
   if ('run' in row) return row.run[0]
+  if ('task' in row) return row.task
   return undefined
 }
 
@@ -38,27 +49,66 @@ export function gapBefore(rows: TranscriptRow[], index: number): boolean {
   return needsBlank(before, after)
 }
 
+/**
+ * Which items each task block absorbed, as itemIndex → rowIndex — the one
+ * lookup {@link rowIndexForItem} cannot answer from ordering (see its comment).
+ * Memoized per rows array identity: the shell builds `rows` in a `useMemo`, so
+ * within one row list this is built once, and a WeakMap means a discarded list
+ * takes its map with it. Memoization only — the answer is a pure function of
+ * the array.
+ */
+const absorbedCache = new WeakMap<readonly TranscriptRow[], Map<number, number>>()
+
+function absorbedRows(rows: readonly TranscriptRow[]): Map<number, number> {
+  const hit = absorbedCache.get(rows)
+  if (hit) return hit
+  const map = new Map<number, number>()
+  rows.forEach((row, rowIndex) => {
+    if ('task' in row) for (const itemIndex of row.childIndices) map.set(itemIndex, rowIndex)
+  })
+  absorbedCache.set(rows, map)
+  return map
+}
+
 /**
  * Transcript-item index → virtual-row index — **the off-by-a-fold trap.**
  *
  * The virtualizer's rows are {@link TerminalBlock}s, not items: a folded tool
- * run occupies ONE row for `run.length` consecutive items, and the recap
- * boundary is a row with *no* item index at all, shifting every row after it
- * by one. `virtualizer.scrollToIndex(itemIndex)` is therefore wrong by
- * construction on any folded or spliced transcript — every jump that starts
- * from an item (the scrubber's marks, a future bookmark) must come through
- * here first.
+ * run occupies ONE row for `run.length` consecutive items, a task block
+ * occupies ONE row for its `Task` call *plus every item its subagent produced*,
+ * and the recap boundary is a row with *no* item index at all, shifting every
+ * row after it by one. `virtualizer.scrollToIndex(itemIndex)` is therefore
+ * wrong by construction on any folded or spliced transcript — every jump that
+ * starts from an item (the scrubber's marks, a future bookmark) must come
+ * through here first.
  *
- * The rule: the **last non-recap row whose first item index is ≤ the target**.
- * Rows are ordered by `index` (a run's row covers
- * `[index, index + run.length)`), so this is a binary search; the recap row
- * is skipped by giving it its successor's start for navigation (both qualify
- * at the boundary, and "last wins" lands on the real row) while never letting
- * it be the answer. Exhaustively checked against a linear reference — every
- * fixture × every item index × several splice positions — by
- * `__wdCheckMapping` in `dev/App.tsx`.
+ * The contract, in two halves:
+ *
+ * - An index a task block **absorbed** maps to that block's row, wherever the
+ *   child fell in the stream. Subagents run in parallel, so absorbed indices
+ *   interleave arbitrarily with later rows' starts — no ordering argument can
+ *   find their row, which is why they are answered first, from a per-row-list
+ *   map ({@link absorbedRows}) built once per rows array. A row's coverage is
+ *   its `childIndices`, never `[index, index + N)` arithmetic.
+ * - Every other index maps to the **last non-recap row whose start (`index`)
+ *   is ≤ the target** — the original rule, still a binary search. Rows stay
+ *   ordered by `index`, and the ordering argument is now: between one row's
+ *   start and the next row's, every index is either absorbed (answered above)
+ *   or a member of the earlier row — note that is *weaker* than the old
+ *   contiguity claim, because a run can fold across an absorbed gap (two
+ *   top-level calls separated only by a subagent's step are adjacent on
+ *   screen), so `[index, index + run.length)` arithmetic no longer describes
+ *   a run's coverage; membership does. The recap row is skipped by giving it
+ *   its successor's start for navigation (both qualify at the boundary, and
+ *   "last wins" lands on the real row) while never letting it be the answer.
+ *
+ * Exhaustively checked against a linear reference — every fixture × every item
+ * index × several splice positions — by `__wdCheckMapping` in `dev/App.tsx`,
+ * and against constructed interleavings in `test/transcript-rows.test.ts`.
  */
 export function rowIndexForItem(rows: readonly TranscriptRow[], itemIndex: number): number {
+  const absorbed = absorbedRows(rows).get(itemIndex)
+  if (absorbed !== undefined) return absorbed
   let lo = 0
   let hi = rows.length - 1
   let best = 0
@@ -80,3 +130,52 @@ export function rowIndexForItem(rows: readonly TranscriptRow[], itemIndex: numbe
   }
   return best
 }
+
+/** Where an item sits inside a row it shares with other items: its 0-based
+ * ordinal in stream order, out of `count` siblings. `0 ≤ ordinal < count`. */
+export type RowPosition = { ordinal: number; count: number }
+
+const positionCache = new WeakMap<readonly TranscriptRow[], Map<number, RowPosition>>()
+
+function rowPositions(rows: readonly TranscriptRow[]): Map<number, RowPosition> {
+  const hit = positionCache.get(rows)
+  if (hit) return hit
+  const map = new Map<number, RowPosition>()
+  for (const row of rows) {
+    if ('task' in row) {
+      const count = row.childIndices.length
+      row.childIndices.forEach((itemIndex, ordinal) => map.set(itemIndex, { ordinal, count }))
+    } else if ('run' in row && row.run.length > 1) {
+      const count = row.run.length
+      row.indices.forEach((itemIndex, ordinal) => map.set(itemIndex, { ordinal, count }))
+    }
+  }
+  positionCache.set(rows, map)
+  return map
+}
+
+/**
+ * Where an item sits inside a row that holds MORE than itself — a task block's
+ * absorbed child, or a member of a folded run of two or more. `undefined` for
+ * everything else, including a row's own head item (the `Task` call, a run's
+ * first member is *not* exempt) and a **singleton run**: there the row's extent
+ * IS the item's, and a mark spanning it is honest.
+ *
+ * That carve-out is load-bearing rather than tidy: `pushLeaf` makes *every*
+ * top-level tool call a `RunBlock`, usually of length 1, so without it every
+ * ordinary failed call's scrubber mark would shrink from its row's extent to a
+ * tick and the rail would stop reading as a map — a regression traded for a fix.
+ *
+ * The scrubber is the consumer: a mark for a shared-row item anchors at
+ * `ordinal / count` of the row's *measured* height instead of inheriting an
+ * extent that is mostly other items' work (one failed child of a hundred-call
+ * task painted the whole expanded block red). Memoized per rows array identity
+ * exactly like {@link absorbedRows}, and pure — the answer is a function of the
+ * array alone, and a discarded array takes its map with it.
+ */
+export function positionInRow(
+  rows: readonly TranscriptRow[],
+  itemIndex: number,
+): RowPosition | undefined {
+  return rowPositions(rows).get(itemIndex)
+}

package/src/components/terminal/TerminalTranscript.tsx

@@ -2,6 +2,7 @@ import { Fragment, useEffect, useMemo, useState } from 'react'
 import type { TranscriptItem, TranscriptState } from '@workerdeck/react'
 import { cn } from '../../lib/utils.ts'
 import type { TerminalAffordances } from './affordances.tsx'
+import { OpenSubagentAction, WithActions } from './affordances.tsx'
 import {
   AssistantRow,
   FileRow,
@@ -13,9 +14,15 @@ import {
   UserRow,
   WorkingRow,
   blockNeedsBlank,
+  taskChildItems,
   terminalBlocks,
+  type TaskBlock,
 } from './items.tsx'
-import { Blank } from './row.tsx'
+import { usePulse } from '../agent/pulse.tsx'
+import { Pressable, useRevealOnOpen } from './press.tsx'
+import { taskBrief, taskBusy, taskFailed, taskSummary } from './tool-run.ts'
+import { BRIEF_LINES } from './height.ts'
+import { Blank, Row } from './row.tsx'
 import { TerminalSurface } from './surface.tsx'
 
 /**
@@ -79,6 +86,149 @@ export function TerminalItemView({
   }
 }
 
+/**
+ * A `Task` and everything the subagent it spawned produced, as one row.
+ *
+ * The same claim the tool-run fold makes, and a stronger one: a subagent is
+ * *sixty* rows of somebody else's working — a brief, a dozen greps, its own
+ * thinking — and none of it is what you came back to read. What you came back
+ * to read is the report, and the report is the model's next sentence. So the
+ * whole frame collapses to one line saying what was asked and how big the
+ * answer was, and opens in full the moment it is the thing you want.
+ *
+ * **Always collapsed when unmounted**, and that is load-bearing rather than
+ * tidy: `height.ts` predicts this row as exactly one wrapped `taskSummary`, and
+ * expansion is component-local state that dies with the row. A row auto-opening
+ * because its subagent happens to be running would make its own height
+ * unpredictable — which is why the live signal is *in* the collapsed line (the
+ * pulse, and a count that climbs) rather than in an open block.
+ *
+ * The children are the theme's ordinary rows, stepped in behind a rule, and
+ * they fold among themselves: a subagent's consecutive tool calls are as much
+ * an aside inside its frame as they are in the main thread.
+ */
+/**
+ * **What the agent was asked** — the sub-agent's brief, clipped to
+ * {@link BRIEF_LINES} and pressable for the whole of it.
+ *
+ * It leads the takeover's frame and the inline task expansion alike, because
+ * both are answering the same question and an answer without its question is
+ * half a transcript. This is the one row here built from something other than
+ * the stream, and it exists for the case the stream does not cover: a
+ * **background** agent forwards no brief, where a foreground `Task` forwards a
+ * real nested user item that renders as an ordinary prompt row. The callers
+ * splice this in only when that row is absent. Codex draws nothing either way —
+ * its spawn message is encrypted on the wire, so there is no brief to give.
+ *
+ * `>` and blue, the prompt's own marker and colour, because that is what this
+ * is: somebody's instruction, one level in. The clip is `line-clamp`, which
+ * cuts on the same wrapped lines `briefPx` counts — one rule, so the reserved
+ * height and the drawn height cannot disagree.
+ */
+export function BriefRow({ text, terminal }: { text: string; terminal?: boolean }) {
+  const [open, setOpen] = useState(false)
+  if (!terminal) {
+    return (
+      <div data-slot='brief' className='px-4 py-2 text-body-sm whitespace-pre-wrap text-fg-2'>
+        {text}
+      </div>
+    )
+  }
+  return (
+    <div data-slot='brief'>
+      <Pressable onPress={() => setOpen((v) => !v)} expanded={open}>
+        <Row glyph='>' glyphTone='blue' tone='dim'>
+          <span
+            className={cn('whitespace-pre-wrap', !open && 'term-brief-clip')}
+            style={open ? undefined : { WebkitLineClamp: BRIEF_LINES }}>
+            {text}
+          </span>
+        </Row>
+      </Pressable>
+    </div>
+  )
+}
+
+export function TaskRow({
+  block,
+  fileUrl,
+  onOpenSubagent,
+}: {
+  block: TaskBlock
+  fileUrl?: (path: string) => string
+  /** Take over the panel with this sub-agent's own frame. Absent draws no
+   * affordance at all — the plain renderer has no surface to take over, and an
+   * action that opens nothing is worse than no action. */
+  onOpenSubagent?: (toolUseId: string) => void
+}) {
+  const [open, setOpen] = useState(false)
+  const reveal = useRevealOnOpen(open)
+  const children = useMemo(() => taskChildItems(block), [block])
+  // Only when the sub-agent's own stream carries no brief — a foreground Task
+  // forwards one as a real user item, and two spellings of one instruction is
+  // worse than none. See `taskBrief`.
+  const brief = children.some((item) => item.kind === 'user') ? undefined : taskBrief(block.task)
+  const busy = taskBusy(block.task, children)
+  const failed = taskFailed(block.task)
+  const pulse = usePulse(busy)
+
+  const row = (
+    <div ref={reveal} className={open ? 'term-open' : undefined}>
+      <Pressable onPress={() => setOpen((v) => !v)} expanded={open}>
+        {/* A marker, where a folded run of calls gets none: a run is an aside,
+            but delegating a piece of the work is something the model *did*, and
+            the row stands for the whole of it. The body is `taskSummary`
+            verbatim — it is the string `height.ts` wraps to size this row, and
+            a second spelling here would be a second height. */}
+        {/* Green means sub-agent, and it means it here for the same reason it
+            means it on the rail: every other colour is spoken for — blue is
+            you, white is the answer, red is an alarm, magenta is your bookmark,
+            yellow is the session waiting on you (see `terminal.css`). The
+            *body* is green and the marker is not: a green glyph already means
+            "wrote to the workspace" a few rows down, and one colour cannot mean
+            two things in the same gutter. Failure still outranks it — an alarm
+            is not a category. */}
+        <Row
+          glyph={busy ? pulse : '●'}
+          glyphTone={failed ? 'red' : busy ? 'mark' : 'dim'}
+          tone={failed ? 'red' : 'green'}>
+          {taskSummary(block.task, children)}
+        </Row>
+      </Pressable>
+      {open ? (
+        // `term-nested` and not the shell's cards-era `border-l-2 pl-3`: this
+        // sits on the open block's wash, where that border token is invisible,
+        // and its 14px would take every nested marker off the cell grid.
+        <div className='term-nested'>
+          {/* The brief leads the children for the same reason it leads the
+              frame: the instruction, then the work. */}
+          {brief ? <BriefRow text={brief} terminal /> : null}
+          {block.children.map((leaf, index) => (
+            <Fragment key={leaf.key}>
+              {index > 0 && blockNeedsBlank(block.children[index - 1]!, leaf) ? <Blank /> : null}
+              {'run' in leaf ? (
+                <ToolRunRow items={leaf.run} />
+              ) : (
+                <TerminalItemView item={leaf.item} fileUrl={fileUrl} />
+              )}
+            </Fragment>
+          ))}
+        </div>
+      ) : null}
+    </div>
+  )
+  // Wrapped only when there is somewhere to go. `WithActions` is a no-op when
+  // affordances are off, but wrapping unconditionally would still put an
+  // "open" glyph on a renderer that cannot honour it.
+  return onOpenSubagent === undefined ? (
+    row
+  ) : (
+    <WithActions actions={<OpenSubagentAction onOpen={() => onOpenSubagent(block.task.id)} />}>
+      {row}
+    </WithActions>
+  )
+}
+
 /** When the current run began — the clock the working line counts from. Held
  * here, not in the row, because the row comes and goes within a single turn (it
  * hides the moment text streams) and a clock restarting at every tool call
@@ -127,8 +277,10 @@ export function TerminalTranscript({
           {index > 0 && blockNeedsBlank(blocks[index - 1]!, block) ? <Blank /> : null}
           {'run' in block ? (
             <ToolRunRow items={block.run} />
-          ) : (
+          ) : 'item' in block ? (
             <TerminalItemView item={block.item} fileUrl={fileUrl} />
+          ) : (
+            <TaskRow block={block} fileUrl={fileUrl} />
           )}
         </Fragment>
       ))}

package/src/components/terminal/affordances.tsx

@@ -89,6 +89,40 @@ export function WithActions({
  * else is on, and reads as a button borrowed from another application. The tick
  * replaces the glyph in place, so the confirmation costs no width either.
  */
+/**
+ * Open a sub-agent's own surface, as a character.
+ *
+ * A row **action** and not the row's press, because the press already means
+ * expand/collapse and that is the cheaper, more common intent — a reader
+ * glancing at what an agent did wants the four rows inline, not a new screen.
+ * Taking over the panel is the deliberate move, so it gets the deliberate
+ * target. Same zero-layout contract as `CopyAction`: it lives in the hover
+ * actions overlay, so a collapsed Task row is exactly as tall with it as
+ * without, which is what keeps the height book honest.
+ */
+export function OpenSubagentAction({
+  onOpen,
+  label = 'Open sub-agent',
+}: {
+  onOpen: () => void
+  label?: string
+}) {
+  return (
+    <button
+      type='button'
+      className='term-action'
+      title={label}
+      aria-label={label}
+      onClick={(event) => {
+        // The row underneath expands; opening is not expanding.
+        event.stopPropagation()
+        onOpen()
+      }}>
+      ⤢
+    </button>
+  )
+}
+
 export function CopyAction({ text, label = 'Copy' }: { text: string; label?: string }) {
   const [copied, setCopied] = useState(false)
   return (