@workerdeck/ui 0.16.0 → 0.17.0

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,23 @@
 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. */
+/** 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 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 +41,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 +122,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

@@ -13,9 +13,14 @@ 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 { taskBusy, taskFailed, taskSummary } from './tool-run.ts'
+import { Blank, Row } from './row.tsx'
 import { TerminalSurface } from './surface.tsx'
 
 /**
@@ -79,6 +84,77 @@ 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.
+ */
+export function TaskRow({
+  block,
+  fileUrl,
+}: {
+  block: TaskBlock
+  fileUrl?: (path: string) => string
+}) {
+  const [open, setOpen] = useState(false)
+  const reveal = useRevealOnOpen(open)
+  const children = useMemo(() => taskChildItems(block), [block])
+  const busy = taskBusy(block.task, children)
+  const failed = taskFailed(block.task)
+  const pulse = usePulse(busy)
+
+  return (
+    <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. */}
+        <Row
+          glyph={busy ? pulse : '●'}
+          glyphTone={failed ? 'red' : busy ? 'mark' : 'dim'}
+          tone={failed ? 'red' : 'fg'}>
+          {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'>
+          {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>
+  )
+}
+
 /** 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 +203,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>
       ))}