@workerdeck/ui 2.13.0 → 2.14.0

package/src/components/agent/use-shell-frame.ts

@@ -0,0 +1,111 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import type { SessionInfo, ShellInfo } from '@workerdeck/protocol'
+import type { ShellItem, TranscriptItem } from '@workerdeck/react'
+
+export type ShellFrameOptions = {
+  sessionId: string | undefined
+  items: readonly TranscriptItem[]
+  session: SessionInfo | undefined
+  shells?: readonly ShellInfo[]
+  reveal?: { toolUseId: string; nonce: number }
+  openShell?: { shellId: string; nonce: number }
+  onShellChange?: (shellId: string | undefined) => void
+}
+
+export type ShellFrame = {
+  shellId: string | undefined
+  enterShell: (shellId: string) => void
+  leaveShell: () => void
+  returnReveal: { toolUseId: string; nonce: number } | undefined
+  shell: ShellInfo | undefined
+  label: string
+}
+
+// The shell frame machine, the sub-agent frame's twin: entry keys on the nonce alone, Escape
+// leaves, and the report is deduped through a ref so an echo of our own report is inert.
+export function useShellFrame(options: ShellFrameOptions): ShellFrame {
+  const { sessionId, items, session, shells, reveal, openShell, onShellChange } = options
+
+  const [shellId, setShellId] = useState<string | undefined>(undefined)
+  const [returnReveal, setReturnReveal] = useState<{ toolUseId: string; nonce: number } | undefined>(undefined)
+  useEffect(() => {
+    setShellId(undefined)
+    setReturnReveal(undefined)
+  }, [sessionId])
+
+  const rowIdRef = useRef<string | undefined>(undefined)
+  const row = useMemo(
+    () => (shellId === undefined ? undefined : items.find((item): item is ShellItem => item.kind === 'shell' && item.shell.id === shellId)),
+    [items, shellId],
+  )
+  rowIdRef.current = row?.id
+
+  // Leaving reveals the `$` row the frame came from, so the reader lands where they left.
+  const leaveShell = useCallback(() => {
+    setShellId((current) => {
+      const rowId = rowIdRef.current
+      if (current !== undefined && rowId !== undefined) {
+        setReturnReveal({ toolUseId: rowId, nonce: Date.now() })
+      }
+      return undefined
+    })
+  }, [])
+
+  const openShellNonce = openShell?.nonce
+  const openShellId = openShell?.shellId
+  useEffect(() => {
+    if (openShellId === undefined) {
+      leaveShell()
+    } else {
+      setShellId(openShellId)
+    }
+    // Keyed on the nonce alone: an unchanged nonce is the host echoing our own report, and
+    // acting on it starts the URL -> panel -> URL cycle.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [openShellNonce])
+
+  const revealNonce = reveal?.nonce
+  useEffect(() => {
+    if (revealNonce === undefined) {
+      return
+    }
+    setShellId(undefined)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [revealNonce])
+
+  useEffect(() => {
+    if (shellId === undefined) {
+      return
+    }
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key !== 'Escape' || event.defaultPrevented) {
+        return
+      }
+      leaveShell()
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [shellId, leaveShell])
+
+  const onShellChangeRef = useRef(onShellChange)
+  onShellChangeRef.current = onShellChange
+  const reportedShellId = useRef<string | undefined>(undefined)
+  useEffect(() => {
+    if (reportedShellId.current === shellId) {
+      return
+    }
+    reportedShellId.current = shellId
+    onShellChangeRef.current?.(shellId)
+  }, [shellId])
+
+  const shell = useMemo(() => {
+    if (shellId === undefined) {
+      return undefined
+    }
+    return row?.shell ?? shells?.find((record) => record.id === shellId) ?? session?.shells?.find((record) => record.id === shellId)
+  }, [row, shells, session, shellId])
+
+  const label = shell ? shell.label || shell.command.split('\n')[0] || 'shell' : 'shell'
+
+  return { shellId, enterShell: setShellId, leaveShell, returnReveal, shell, label }
+}

package/src/components/terminal/TerminalTranscript.tsx

@@ -10,6 +10,7 @@ import {
   NoticeRow,
   PeerSendRow,
   RunRow,
+  ShellRow,
   ThinkingRow,
   ToolRow,
   TurnResultRow,
@@ -60,6 +61,9 @@ export function TerminalItemView({ item, fileUrl }: { item: TranscriptItem; file
     case 'file_delivered': {
       return <FileRow item={item} href={fileUrl?.(item.path)} />
     }
+    case 'shell': {
+      return <ShellRow item={item} />
+    }
     default: {
       return null
     }

package/src/components/terminal/affordances.tsx

@@ -1,5 +1,6 @@
 import { createContext, useContext, useState, type ReactNode } from 'react'
 import { copyText } from '../../lib/clipboard.ts'
+import { SHELL_KILL_GLYPH } from './shell-row.ts'
 import { cn } from '../../lib/utils.ts'
 
 export type TerminalAffordances = {
@@ -97,6 +98,42 @@ export function OpenSubagentAction({ onOpen, label = 'Open sub-agent' }: { onOpe
   )
 }
 
+export function OpenShellAction({ onOpen, label = 'Open terminal' }: { onOpen: () => void; label?: string }) {
+  return (
+    <button
+      type="button"
+      className="term-action"
+      title={label}
+      aria-label={label}
+      data-tone="magenta"
+      onClick={(event) => {
+        event.stopPropagation()
+        onOpen()
+      }}
+    >
+      ⤢
+    </button>
+  )
+}
+
+export function KillShellAction({ onKill, label = 'Kill this shell' }: { onKill: () => void; label?: string }) {
+  return (
+    <button
+      type="button"
+      className="term-action"
+      title={label}
+      aria-label={label}
+      data-tone="red"
+      onClick={(event) => {
+        event.stopPropagation()
+        onKill()
+      }}
+    >
+      {SHELL_KILL_GLYPH}
+    </button>
+  )
+}
+
 export function CopyAction({ text, label = 'Copy' }: { text: string; label?: string }) {
   const [copied, setCopied] = useState(false)
   return (

package/src/components/terminal/height.ts

@@ -4,6 +4,7 @@ import { compactionText, formatBytes, formatCost, formatDuration, toolInputPrevi
 import { taskChildItems, type TerminalBlock, type ToolCallItem } from './blocks.ts'
 import { IMAGE_BOX_LINES } from './image-box.ts'
 import { collapsedResult } from './result-preview.ts'
+import { shellBodyLines, shellFooterText, shellHeaderText } from './shell-row.ts'
 import { todoLine, todoPreview } from './todos.ts'
 import { isPeerSend, peerName, planRun, runSummary, taskSummary } from './tool-run.ts'
 
@@ -634,6 +635,19 @@ export function itemHeight(item: TranscriptItem, m: CellMetrics): ComputedHeight
       const text = `${item.path} · ${formatBytes(item.bytes)}` + (item.description ? ` · ${item.description}` : '')
       return rowH(text, m, { extraPx })
     }
+    case 'shell': {
+      // Collapsed, as the row first draws: expanding is a state change the epoch's cache is invalidated by anyway.
+      const lines = shellBodyLines(item, false)
+      let acc = rowH(shellHeaderText(item), m, { extraPx })
+      for (const line of lines) {
+        acc = add(acc, rowH(line || ' ', m, { extraPx }))
+      }
+      const footer = shellFooterText(item, false, lines.length)
+      if (footer) {
+        acc = add(acc, rowH(footer, m, { extraPx }))
+      }
+      return acc
+    }
     default: {
       return { px: 0, exact: false }
     }

package/src/components/terminal/items.tsx

@@ -1,15 +1,15 @@
 import { useEffect, useState, type ReactNode } from 'react'
 import type { MessageOrigin } from '@workerdeck/protocol'
-import type { TranscriptItem } from '@workerdeck/react'
+import type { ShellItem, TranscriptItem } from '@workerdeck/react'
 import { compactionText, formatBytes, formatCost, formatDuration, toolInputPreview } from '../../lib/format.ts'
 import { isMutatingTool } from '../../lib/tool-icon.ts'
 import { usePulse } from '../agent/pulse.tsx'
 import { PromptTokenText } from '../agent/PromptTokenText.tsx'
-import { BookmarkAction, CopyAction, WithActions } from './affordances.tsx'
+import { BookmarkAction, CopyAction, KillShellAction, OpenShellAction, WithActions } from './affordances.tsx'
 import { TerminalDiff } from './diff.tsx'
 import { TerminalMarkdown } from './markdown.tsx'
 import { usePeerNames } from './peer-names.tsx'
-import { Pressable, useRevealOnOpen } from './press.tsx'
+import { Pressable, useRevealOnOpen, type PressModifiers } from './press.tsx'
 import { IMAGE_BOX_LINES, IMAGE_UNAVAILABLE, imagePlaceholder } from './image-box.ts'
 import { collapsedResult } from './result-preview.ts'
 import { useToolResultFetcher } from '../agent/tool-result-fetch.tsx'
@@ -17,6 +17,8 @@ import { useToolTitle } from '../agent/tool-titles.tsx'
 import { useToolResultImageSrc } from '../agent/tool-result-image.tsx'
 import { isPeerSend, peerName, peerOneLine, peerSendTarget, peerSendText, planRun, runFailed, runSummary } from './tool-run.ts'
 import { todoLine, todoPreview, type TodoPreview, type TodoStatus } from './todos.ts'
+import { useShellActions } from '../agent/shell-actions.tsx'
+import { SHELL_GLYPH, shellBodyLines, shellFailed, shellFooterText, shellLabel, shellStatusText } from './shell-row.ts'
 import { type ToolCallItem } from './blocks.ts'
 import { Band, Blank, Ink, Row, type Tone } from './row.tsx'
 
@@ -386,6 +388,73 @@ export function NoticeRow({ item }: { item: Extract<TranscriptItem, { kind: 'not
   )
 }
 
+export function ShellRow({ item }: { item: ShellItem }) {
+  const [open, setOpen] = useState(false)
+  const [busy, setBusy] = useState(false)
+  const actions = useShellActions()
+  const reveal = useRevealOnOpen(open)
+  const running = item.shell.status === 'running'
+  const failed = shellFailed(item)
+  const tone: Tone = failed ? 'red' : running ? 'magenta' : 'dim'
+  const lines = shellBodyLines(item, open)
+  const footer = shellFooterText(item, open, lines.length)
+
+  const shellId = item.shell.id
+  const verify = actions.verify
+  useEffect(() => {
+    if (running) {
+      void verify(shellId)
+    }
+  }, [running, shellId, verify])
+
+  const press = (modifiers: PressModifiers) => {
+    if ((modifiers.meta || modifiers.ctrl) && actions.open) {
+      actions.open(shellId)
+      return
+    }
+    const next = !open
+    setOpen(next)
+    if (!next || !item.truncated || item.expanded !== undefined || item.missing) {
+      return
+    }
+    setBusy(true)
+    void actions.loadOutput(shellId).finally(() => setBusy(false))
+  }
+
+  return (
+    <div ref={reveal} className={open ? 'term-open' : undefined}>
+      <WithActions
+        actions={
+          <>
+            {actions.open ? <OpenShellAction onOpen={() => actions.open?.(shellId)} /> : null}
+            {running ? <KillShellAction onKill={() => void actions.kill(shellId)} /> : null}
+            <BookmarkAction id={item.id} />
+            <CopyAction text={item.shell.command} label="Copy command" />
+          </>
+        }
+      >
+        <Pressable onPress={press} expanded={open}>
+          <Row glyph={SHELL_GLYPH} glyphTone={tone} tone="fg">
+            <Ink bold tone="bright">
+              {shellLabel(item)}
+            </Ink>
+            <Ink tone={failed ? 'red' : 'faint'}>
+              {' · '}
+              {shellStatusText(item)}
+            </Ink>
+          </Row>
+        </Pressable>
+        {lines.map((line, index) => (
+          <Row key={index} tone={failed ? 'red' : 'dim'}>
+            {line || ' '}
+          </Row>
+        ))}
+        {footer || busy ? <Row tone="faint">{busy ? '… fetching the full output' : footer}</Row> : null}
+      </WithActions>
+    </div>
+  )
+}
+
 export function FileRow({ item, href }: { item: Extract<TranscriptItem, { kind: 'file_delivered' }>; href?: string }) {
   return (
     <Row glyph="⤓" glyphTone="blue" tone="dim">

package/src/components/terminal/press.tsx

@@ -3,13 +3,15 @@ import { cn } from '../../lib/utils.ts'
 
 const DRAG_SLOP = 4
 
+export type PressModifiers = { meta: boolean; ctrl: boolean; alt: boolean }
+
 export function Pressable({
   onPress,
   expanded,
   className,
   children,
 }: {
-  onPress: () => void
+  onPress: (modifiers: PressModifiers) => void
   expanded?: boolean
   className?: string
   children: ReactNode
@@ -34,14 +36,14 @@ export function Pressable({
         if (selection && !selection.isCollapsed && selection.containsNode(event.currentTarget, true)) {
           return
         }
-        onPress()
+        onPress({ meta: event.metaKey, ctrl: event.ctrlKey, alt: event.altKey })
       }}
       onKeyDown={(event) => {
         if (event.key !== 'Enter' && event.key !== ' ') {
           return
         }
         event.preventDefault()
-        onPress()
+        onPress({ meta: event.metaKey, ctrl: event.ctrlKey, alt: event.altKey })
       }}
     >
       {children}

package/src/components/terminal/scrubber.tsx

@@ -7,7 +7,7 @@ import { parentOf } from './blocks.ts'
 import { TerminalSurface } from './surface.tsx'
 
 type Lane = 'l' | 'r' | 'f'
-type MarkKind = 'user' | 'subagent' | 'turn' | 'turnFailed' | 'toolFailed' | 'error' | 'approval' | 'recap' | 'bookmark'
+type MarkKind = 'user' | 'subagent' | 'shell' | 'turn' | 'turnFailed' | 'toolFailed' | 'error' | 'approval' | 'recap' | 'bookmark'
 
 type Mark = {
   kind: MarkKind
@@ -31,6 +31,7 @@ function nearestMember(cluster: Cluster, y: number): Mark | undefined {
 const LANE: Record<MarkKind, Lane> = {
   user: 'l',
   subagent: 'l',
+  shell: 'l',
   turn: 'r',
   turnFailed: 'r',
   toolFailed: 'r',
@@ -49,12 +50,14 @@ const LOUDNESS: Record<MarkKind, number> = {
   turn: 2,
   bookmark: 1,
   subagent: 1,
+  shell: 1,
   recap: 0,
 }
 
 const KIND_NAME: Record<MarkKind, string> = {
   user: 'you',
   subagent: 'sub-agent',
+  shell: 'shell',
   turn: 'response · turn end',
   turnFailed: 'turn failed',
   toolFailed: 'tool failed',
@@ -84,6 +87,9 @@ function excerpt(item: TranscriptItem): string {
     case 'notice': {
       return item.text
     }
+    case 'shell': {
+      return item.shell.command
+    }
     case 'tool_call': {
       return `${item.name}(${toolInputPreview(item.input)})`
     }
@@ -174,6 +180,8 @@ export function buildClusters(props: TerminalScrubberProps, railH: number): Clus
       closeSegment()
     } else if (item.kind === 'notice' && item.level === 'error') {
       marks.push({ kind: 'error', itemIndex: index, rowIndex: rowIndexFor(index) })
+    } else if (item.kind === 'shell') {
+      marks.push({ kind: 'shell', itemIndex: index, rowIndex: rowIndexFor(index) })
     } else if (
       item.kind === 'tool_call' &&
       (item.status === 'failed' || item.result?.isError === true) &&

package/src/components/terminal/shell-row.ts

@@ -0,0 +1,106 @@
+import type { ShellInfo } from '@workerdeck/protocol'
+import type { ShellItem } from '@workerdeck/react'
+
+export const SHELL_GLYPH = '$'
+
+export const SHELL_KILL_GLYPH = '✕'
+
+export const SHELL_EXPAND_CHARS = 100_000
+
+export const SHELL_MISSING = 'output expired or not tracked by this gateway'
+
+export function shellInfoLabel(shell: ShellInfo): string {
+  return shell.label || shell.command.split('\n')[0] || ''
+}
+
+export function shellTitle(shell: ShellInfo): string {
+  return `#${shell.ordinal} ${shellInfoLabel(shell)}`
+}
+
+export function shellLabel(item: ShellItem): string {
+  return shellInfoLabel(item.shell)
+}
+
+export function shellStatusText(item: ShellItem): string {
+  return shellInfoStatusText(item.shell)
+}
+
+export function shellInfoFailed(shell: ShellInfo): boolean {
+  return shell.status === 'exited' && shell.exitCode !== 0
+}
+
+export function shellInfoStatusText(shell: ShellInfo): string {
+  if (shell.status === 'running') {
+    return 'running'
+  }
+  if (typeof shell.exitCode === 'number') {
+    return shell.exitCode === 0 ? 'exit 0' : `exit ${shell.exitCode}`
+  }
+  switch (shell.endReason) {
+    case 'killed': {
+      return 'killed'
+    }
+    case 'timeout': {
+      return 'timed out'
+    }
+    case 'server_stopped': {
+      return 'killed: the gateway stopped'
+    }
+    case 'server_restarted': {
+      return 'ended: the gateway restarted, the process may still be running'
+    }
+    case 'spawn_failed': {
+      return 'failed to start'
+    }
+    default: {
+      return 'ended'
+    }
+  }
+}
+
+export function shellFailed(item: ShellItem): boolean {
+  return shellInfoFailed(item.shell)
+}
+
+export function shellHeaderText(item: ShellItem): string {
+  return `${shellLabel(item)} · ${shellStatusText(item)}`
+}
+
+export function shellBodyLines(item: ShellItem, open: boolean): string[] {
+  const source = open && item.expanded !== undefined ? item.expanded : item.text
+  if (source === '') {
+    return []
+  }
+  const lines = source.split('\n')
+  if (!open) {
+    return lines
+  }
+  const kept: string[] = []
+  let chars = 0
+  for (const line of lines) {
+    if (kept.length > 0 && chars + line.length > SHELL_EXPAND_CHARS) {
+      break
+    }
+    kept.push(line)
+    chars += line.length + 1
+  }
+  return kept
+}
+
+// The footer is the row's one affordance line: what expanding will fetch, what it clipped, or why it cannot.
+export function shellFooterText(item: ShellItem, open: boolean, shown: number): string | undefined {
+  if (item.missing) {
+    return SHELL_MISSING
+  }
+  if (!open) {
+    return item.truncated ? '… more output - expand to fetch it' : undefined
+  }
+  const total = item.expanded === undefined ? undefined : item.expanded.split('\n').length
+  if (total !== undefined && total > shown) {
+    return `… +${(total - shown).toLocaleString()} lines not shown`
+  }
+  if (item.expanded === undefined && item.truncated) {
+    return '… fetching the full output'
+  }
+  return undefined
+}

package/src/index.ts

@@ -125,7 +125,7 @@ export { SessionBrowser, rowShapeClass, type SessionBrowserProps } from './compo
 export { SessionItem, type SelectModifiers, type SessionItemProps } from './components/agent/SessionItem.tsx'
 export { SessionStatusIcon } from './components/agent/SessionStatusIcon.tsx'
 export { EngineIcon, engineMark, vendorMarkClass, vendorTextClass } from './components/agent/EngineIcon.tsx'
-export { type Step, StepRow, sessionSteps } from './components/agent/SessionSteps.tsx'
+export { type ShellStepOptions, type Step, type StepKind, StepRow, sessionSteps } from './components/agent/SessionSteps.tsx'
 export {
   SUBAGENT_DISPLAY_META,
   SUBAGENT_DISPLAY_ORDER,
@@ -134,6 +134,17 @@ export {
   type SubagentToggleProps,
 } from './components/agent/SubagentToggle.tsx'
 export { SubagentStrip } from './components/agent/SubagentStrip.tsx'
+export { ShellStrip, type ShellStripProps } from './components/agent/ShellStrip.tsx'
+export { useShellFrame, type ShellFrame, type ShellFrameOptions } from './components/agent/use-shell-frame.ts'
+export { ShellActionsProvider, useShellActions, type ShellActions } from './components/agent/shell-actions.tsx'
+export {
+  SHELL_GLYPH,
+  SHELL_KILL_GLYPH,
+  shellInfoFailed,
+  shellInfoLabel,
+  shellInfoStatusText,
+  shellTitle,
+} from './components/terminal/shell-row.ts'
 export { ProjectIcon } from './components/agent/ProjectIcon.tsx'
 export { SessionEmptyState, type SessionEmptyStateProps } from './components/agent/SessionEmptyState.tsx'
 export { PromptTokenText, SessionNamesProvider, SkillNamesProvider } from './components/agent/PromptTokenText.tsx'

package/src/styles/terminal.css

@@ -470,6 +470,10 @@
   padding: 0;
   cursor: pointer;
 }
+/* The shell drill-in, in the same magenta as the row's `$`. */
+[data-terminal] .term-action[data-tone='magenta'] {
+  color: var(--term-magenta);
+}
 [data-terminal] .term-action:hover {
   color: var(--term-fg);
 }
@@ -1152,6 +1156,13 @@ button.term-link {
 .term-scrubber .term-scrub-mark[data-kind='subagent'] {
   background: linear-gradient(to bottom, var(--term-green) 0 2px, color-mix(in srgb, var(--term-green) 25%, transparent) 2px);
 }
+/* A shell run, in the input lane because a `$` command is something you did:
+   the composer's own magenta, at the bookmark's loudness so a long log never
+   shouts over a failed turn. Drawn as an extent like the marks it shares the
+   lane with. */
+.term-scrubber .term-scrub-mark[data-kind='shell'] {
+  background: linear-gradient(to bottom, var(--wd-shell-accent) 0 2px, color-mix(in srgb, var(--wd-shell-accent) 25%, transparent) 2px);
+}
 .term-scrubber .term-scrub-mark[data-kind='turn'] {
   background: linear-gradient(to bottom, var(--term-fg) 0 2px, color-mix(in srgb, var(--term-fg) 25%, transparent) 2px);
 }

package/src/styles/theme.css

@@ -827,6 +827,9 @@
 .wd-scrubber .wd-scrub-mark[data-kind='subagent'] {
   background: var(--success);
 }
+.wd-scrubber .wd-scrub-mark[data-kind='shell'] {
+  background: var(--wd-shell-accent);
+}
 .wd-scrubber .wd-scrub-mark[data-kind='turn'] {
   background: var(--fg-3);
 }

package/src/workspace.ts

@@ -3,3 +3,4 @@ export { FileTree, type FileTreeProps } from './components/agent/FileTree.tsx'
 export { EditorTabs, type EditorTabsProps } from './components/agent/EditorTabs.tsx'
 export { FileViewer, type FileViewerProps } from './components/agent/FileViewer.tsx'
 export { CodeEditor, type CodeEditorProps } from './components/agent/CodeEditor.tsx'
+export { ShellTerminal, type ShellTerminalProps } from './components/agent/ShellTerminal.tsx'