@workerdeck/ui 2.13.0 → 2.15.0

package/src/components/agent/SessionSteps.tsx

@@ -1,24 +1,41 @@
 import { ArrowRight, Check, CircleAlert } from 'lucide-react'
-import { isAgentRecord, subagentLabel, visibleSubagents } from '@workerdeck/protocol'
-import type { SessionInfo, SubagentDisplay, SubagentInfo } from '@workerdeck/protocol'
+import { isAgentRecord, promotedShells, subagentLabel, visibleSubagents } from '@workerdeck/protocol'
+import type { SessionInfo, ShellInfo, SubagentDisplay, SubagentInfo } from '@workerdeck/protocol'
 import { Spinner } from '../ui/Spinner.tsx'
 import { cn } from '../../lib/utils.ts'
+import { SHELL_GLYPH, SHELL_KILL_GLYPH, shellInfoFailed, shellInfoLabel, shellInfoStatusText, shellTitle } from '../terminal/shell-row.ts'
+
+export type StepKind = 'agent' | 'shell'
 
 export type Step = {
   key: string
+  kind: StepKind
   label: string
   noun: string
   state: 'done' | 'running' | 'failed'
   detail?: string
   title: string
   onSelect: () => void
+  onKill?: () => void
+}
+
+export type ShellStepOptions = {
+  now: number
+  onSelect: (shellId: string) => void
+  onKill?: (shellId: string) => void
 }
 
-export function sessionSteps(info: SessionInfo, onSelect: (toolUseId: string) => void, show: SubagentDisplay = 'all'): Step[] {
-  return visibleSubagents(info, show)
+export function sessionSteps(
+  info: SessionInfo,
+  onSelect: (toolUseId: string) => void,
+  show: SubagentDisplay = 'all',
+  shells?: ShellStepOptions,
+): Step[] {
+  const agents: Step[] = visibleSubagents(info, show)
     .filter(isAgentRecord)
     .map((sub) => ({
       key: sub.toolUseId,
+      kind: 'agent',
       label: subagentLabel(sub),
       noun: 'agent',
       state: stepState(sub.status),
@@ -26,6 +43,26 @@ export function sessionSteps(info: SessionInfo, onSelect: (toolUseId: string) =>
       title: `${subagentLabel(sub)} · ${sub.toolCount} tool${sub.toolCount === 1 ? '' : 's'}`,
       onSelect: () => onSelect(sub.toolUseId),
     }))
+  if (shells === undefined) {
+    return agents
+  }
+  return [...agents, ...promotedShells(info, shells.now).map((shell) => shellStep(shell, shells))]
+}
+
+function shellStep(shell: ShellInfo, options: ShellStepOptions): Step {
+  const status = shellInfoStatusText(shell)
+  const running = shell.status === 'running'
+  return {
+    key: shell.id,
+    kind: 'shell',
+    label: shellInfoLabel(shell),
+    noun: 'shell',
+    state: shellInfoFailed(shell) ? 'failed' : running ? 'running' : 'done',
+    detail: running ? undefined : status,
+    title: `${shellTitle(shell)} · ${status}`,
+    onSelect: () => options.onSelect(shell.id),
+    onKill: running && options.onKill ? () => options.onKill?.(shell.id) : undefined,
+  }
 }
 
 function stepState(status: SubagentInfo['status']): Step['state'] {
@@ -43,33 +80,47 @@ function stepState(status: SubagentInfo['status']): Step['state'] {
 }
 
 export function StepRow({ step, active = false, onSelect }: { step: Step; active?: boolean; onSelect: () => void }) {
-  const body = step.state === 'failed' ? 'text-danger' : 'text-success'
+  const body = step.state === 'failed' ? 'text-danger' : step.kind === 'shell' ? 'text-[var(--wd-shell-accent)]' : 'text-success'
   return (
-    <button
-      type="button"
-      title={step.title}
-      aria-current={active || undefined}
-      onClick={(e) => {
-        e.stopPropagation()
-        onSelect()
-      }}
-      className={cn(
-        'flex w-full items-center gap-1.5 rounded-[4px] py-1 pr-2.5 pl-3.5',
-        'text-left text-micro outline-none',
-        active ? 'bg-row-selected' : 'hover:bg-row-active',
-        body,
-      )}
-    >
-      <StepIcon state={step.state} />
-      <span className="min-w-0 flex-1 truncate">{step.label}</span>
-      {step.detail ? <span className="shrink-0 tabular-nums text-fg-4">{step.detail}</span> : null}
-      <ArrowRight className="size-3.5 shrink-0 text-fg-4" />
-    </button>
+    <div className={cn('flex w-full items-center rounded-[4px] pr-1.5', active ? 'bg-row-selected' : 'hover:bg-row-active', body)}>
+      <button
+        type="button"
+        title={step.title}
+        aria-current={active || undefined}
+        onClick={(e) => {
+          e.stopPropagation()
+          onSelect()
+        }}
+        className="flex min-w-0 flex-1 items-center gap-1.5 py-1 pr-1 pl-3.5 text-left text-micro outline-none"
+      >
+        <StepIcon step={step} />
+        <span className="min-w-0 flex-1 truncate">{step.label}</span>
+        {step.detail ? <span className="shrink-0 tabular-nums text-fg-4">{step.detail}</span> : null}
+        <ArrowRight className="size-3.5 shrink-0 text-fg-4" />
+      </button>
+      {step.onKill ? (
+        <button
+          type="button"
+          aria-label={`Kill ${step.label}`}
+          title="Kill this shell"
+          onClick={(e) => {
+            e.stopPropagation()
+            step.onKill?.()
+          }}
+          className="shrink-0 px-1 text-micro leading-none text-fg-4 outline-none hover:text-danger"
+        >
+          {SHELL_KILL_GLYPH}
+        </button>
+      ) : null}
+    </div>
   )
 }
 
-function StepIcon({ state }: { state: Step['state'] }) {
-  switch (state) {
+function StepIcon({ step }: { step: Step }) {
+  if (step.kind === 'shell') {
+    return <span className="w-[11px] shrink-0 text-center leading-none">{SHELL_GLYPH}</span>
+  }
+  switch (step.state) {
     case 'running': {
       return <Spinner className="size-[11px] shrink-0" />
     }

package/src/components/agent/SessionWorkspace.tsx

@@ -27,6 +27,9 @@ export interface SessionWorkspaceProps {
   reveal?: SessionPanelProps['reveal']
   subagents?: SessionPanelProps['subagents']
   onSubagentChange?: SessionPanelProps['onSubagentChange']
+  openShell?: SessionPanelProps['openShell']
+  shells?: SessionPanelProps['shells']
+  onShellChange?: SessionPanelProps['onShellChange']
   statusPlacement?: SessionPanelProps['statusPlacement']
   controlsSurface?: SessionPanelProps['controlsSurface']
   fontSize?: SessionPanelProps['fontSize']
@@ -61,6 +64,9 @@ export function SessionWorkspace({
   reveal,
   subagents,
   onSubagentChange,
+  openShell,
+  shells,
+  onShellChange,
   statusPlacement,
   controlsSurface,
   fontSize,
@@ -132,7 +138,7 @@ export function SessionWorkspace({
     container: column,
     onOpen: openPath,
     enabled: tree.available,
-    ignore: '.monaco-editor',
+    ignore: '.monaco-editor, .xterm',
   })
   const editorMax = Math.max(EDITOR_MIN, columnHeight - AGENT_MIN)
 
@@ -221,6 +227,9 @@ export function SessionWorkspace({
             reveal={reveal}
             subagents={subagents}
             onSubagentChange={onSubagentChange}
+            openShell={openShell}
+            shells={shells}
+            onShellChange={onShellChange}
             controlsSurface={controlsSurface}
             fontSize={fontSize}
             onLinkClick={onLinkClick}

package/src/components/agent/ShellStrip.tsx

@@ -0,0 +1,71 @@
+import { ArrowLeft, X } from 'lucide-react'
+import type { ShellInfo } from '@workerdeck/protocol'
+import { cn } from '../../lib/utils.ts'
+import { Button } from '../ui/Button.tsx'
+import { Ink, Row } from '../terminal/row.tsx'
+import { TerminalSurface } from '../terminal/surface.tsx'
+import { shellInfoFailed, shellInfoStatusText, shellTitle } from '../terminal/shell-row.ts'
+import { KillShellAction, WithActions } from '../terminal/affordances.tsx'
+
+export interface ShellStripProps {
+  shell: ShellInfo | undefined
+  label: string
+  cols?: number
+  onBack: () => void
+  onKill?: () => void
+  terminal: boolean
+  fontSize?: number
+  lineHeight?: number
+}
+
+export function ShellStrip({ shell, label, cols, onBack, onKill, terminal, fontSize, lineHeight }: ShellStripProps) {
+  const running = shell?.status === 'running'
+  const failed = shell ? shellInfoFailed(shell) : false
+  const name = shell ? shellTitle(shell) : label
+  const status = shell ? shellInfoStatusText(shell) : undefined
+  const width = cols ?? shell?.cols
+  const detail = width === undefined ? undefined : `${width} cols`
+
+  if (terminal) {
+    return (
+      <TerminalSurface fontSize={fontSize} lineHeight={lineHeight} className="shrink-0">
+        <WithActions actions={running && onKill ? <KillShellAction onKill={onKill} /> : null}>
+          <Row glyph="←" glyphTone="dim" indent={1} tone={failed ? 'red' : 'magenta'}>
+            <button type="button" onClick={onBack} aria-label="Back to the session" className="cursor-pointer text-left">
+              {name}
+            </button>
+            {status ? <Ink tone={failed ? 'red' : running ? 'magenta' : 'dim'}> · {status}</Ink> : null}
+            {detail ? <Ink tone="faint"> · {detail}</Ink> : null}
+          </Row>
+        </WithActions>
+      </TerminalSurface>
+    )
+  }
+
+  return (
+    <div className="flex shrink-0 items-center gap-2 border-b border-border px-3 py-1.5">
+      <Button variant="ghost" size="sm" onClick={onBack} className="h-6 gap-1 px-1.5">
+        <ArrowLeft className="size-3.5" />
+        Back
+      </Button>
+      <span className={cn('min-w-0 flex-1 truncate font-mono text-body-sm', failed ? 'text-danger' : 'text-fg-2')}>{name}</span>
+      {status ? (
+        <span className={cn('shrink-0 text-label', failed ? 'text-danger' : running ? 'text-[var(--wd-shell-accent)]' : 'text-fg-3')}>
+          {status}
+        </span>
+      ) : null}
+      {detail ? <span className="shrink-0 text-label text-fg-4">{detail}</span> : null}
+      {running && onKill ? (
+        <button
+          type="button"
+          aria-label="Kill this shell"
+          title="Kill this shell"
+          className="shrink-0 text-label text-fg-3 hover:text-danger"
+          onClick={onKill}
+        >
+          <X className="size-3.5" />
+        </button>
+      ) : null}
+    </div>
+  )
+}

package/src/components/agent/ShellTerminal.tsx

@@ -0,0 +1,170 @@
+import { useEffect, useRef, useState } from 'react'
+import type { FitAddon } from '@xterm/addon-fit'
+import type { ITheme, Terminal as XTerm } from '@xterm/xterm'
+import { useShellTerminal } from '@workerdeck/react'
+import type { SessionHandle } from '@workerdeck/client'
+import type { ShellInfo } from '@workerdeck/protocol'
+import { cn } from '../../lib/utils.ts'
+import { Spinner } from '../ui/Spinner.tsx'
+
+export interface ShellTerminalProps {
+  handle: SessionHandle | undefined
+  shellId: string | undefined
+  onEnded?: (reason: string) => void
+  onShell?: (shell: ShellInfo) => void
+  fontSize?: number
+  className?: string
+}
+
+export function ShellTerminal({ handle, shellId, onEnded, onShell, fontSize, className }: ShellTerminalProps) {
+  const host = useRef<HTMLDivElement>(null)
+  const term = useRef<XTerm | null>(null)
+  const fit = useRef<FitAddon | null>(null)
+  const [ready, setReady] = useState(false)
+  const attached = useRef(false)
+  const theme = useDocumentTheme()
+  const onShellRef = useRef(onShell)
+  onShellRef.current = onShell
+
+  const shell = useShellTerminal(handle, shellId, {
+    onData: (data) => term.current?.write(data),
+    onAttached: (attachment) => {
+      const instance = term.current
+      if (!instance) {
+        return
+      }
+      instance.reset()
+      if (attachment.scrollback) {
+        instance.write(attachment.scrollback)
+      }
+      // Fit on attach only: a mid-stream refit reflows a cursor-addressed screen under the writer.
+      try {
+        fit.current?.fit()
+      } catch {}
+      onShellRef.current?.(attachment.shell)
+    },
+    onEnded: (reason) => {
+      term.current?.write(`\r\n\x1b[2m[${reason}]\x1b[0m\r\n`)
+      onEnded?.(reason)
+    },
+  })
+  const shellRef = useRef(shell)
+  shellRef.current = shell
+
+  useEffect(() => {
+    let disposed = false
+    void loadXterm().then(({ Terminal, FitAddon: Fit }) => {
+      if (disposed || !host.current) {
+        return
+      }
+      const instance = new Terminal({
+        allowProposedApi: true,
+        convertEol: false,
+        cursorBlink: true,
+        fontSize: fontSize ?? 12,
+        lineHeight: 1.35,
+        fontFamily: 'ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace',
+        theme: xtermTheme(document.documentElement.getAttribute('data-theme')),
+        scrollback: 5000,
+      })
+      const addon = new Fit()
+      instance.loadAddon(addon)
+      instance.open(host.current)
+      addon.fit()
+      instance.onData((data) => shellRef.current.write(data))
+      instance.onResize(({ cols, rows }) => shellRef.current.resize({ cols, rows }))
+      term.current = instance
+      fit.current = addon
+      setReady(true)
+    })
+    return () => {
+      disposed = true
+      attached.current = false
+      shellRef.current.detach()
+      term.current?.dispose()
+      term.current = null
+      fit.current = null
+      setReady(false)
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  useEffect(() => {
+    attached.current = false
+  }, [shellId])
+
+  // The handle reaches this pane a render *after* it mounts, so the attach is driven by all three
+  // becoming true together, never from inside the loader callback.
+  useEffect(() => {
+    const instance = term.current
+    if (!ready || !handle || shellId === undefined || !instance || attached.current) {
+      return
+    }
+    attached.current = true
+    shellRef.current.attach({ cols: instance.cols, rows: instance.rows })
+  }, [ready, handle, shellId])
+
+  useEffect(() => {
+    const instance = term.current
+    if (instance) {
+      instance.options.theme = xtermTheme(theme)
+    }
+  }, [theme])
+
+  useEffect(() => {
+    const node = host.current
+    if (!node || !ready) {
+      return
+    }
+    const observer = new ResizeObserver(() => {
+      try {
+        fit.current?.fit()
+      } catch {}
+    })
+    observer.observe(node)
+    return () => observer.disconnect()
+  }, [ready])
+
+  return (
+    <div className={cn('relative min-h-0 flex-1 overflow-hidden px-2 py-1', className)}>
+      <div ref={host} className="h-full w-full" onClick={() => term.current?.focus()} />
+      {ready && shell.status !== 'idle' ? null : (
+        <div className="absolute inset-0 grid place-items-center">
+          <Spinner />
+        </div>
+      )}
+    </div>
+  )
+}
+
+function useDocumentTheme(): string | null {
+  const [theme, setTheme] = useState<string | null>(() =>
+    typeof document === 'undefined' ? null : document.documentElement.getAttribute('data-theme'),
+  )
+  useEffect(() => {
+    const root = document.documentElement
+    const sync = () => setTheme(root.getAttribute('data-theme'))
+    sync()
+    const observer = new MutationObserver(sync)
+    observer.observe(root, { attributes: true, attributeFilter: ['data-theme'] })
+    return () => observer.disconnect()
+  }, [])
+  return theme
+}
+
+function xtermTheme(theme: string | null): ITheme {
+  return theme === 'light'
+    ? { background: '#00000000', foreground: '#1f2328', cursor: '#1f2328', selectionBackground: '#b9c7d980' }
+    : { background: '#00000000', foreground: '#d4d4d4', cursor: '#d4d4d4', selectionBackground: '#3a4a5f80' }
+}
+
+type XtermApi = { Terminal: typeof XTerm; FitAddon: typeof FitAddon }
+
+let xtermPromise: Promise<XtermApi> | undefined
+function loadXterm(): Promise<XtermApi> {
+  xtermPromise ??= (async () => {
+    const [core, fitAddon] = await Promise.all([import('@xterm/xterm'), import('@xterm/addon-fit')])
+    return { Terminal: core.Terminal, FitAddon: fitAddon.FitAddon }
+  })()
+  return xtermPromise
+}

package/src/components/agent/SubagentToggle.tsx

@@ -49,7 +49,13 @@ export function SubagentToggle({ value, onChange, className }: SubagentTogglePro
     <Menu>
       <MenuTrigger
         render={
-          <Button variant="ghost" size="icon-sm" aria-label={`Sub-agents: ${meta.label}`} title={meta.hint} className={cn('w-9 gap-0.5', className)}>
+          <Button
+            variant="ghost"
+            size="icon-sm"
+            aria-label={`Sub-agents: ${meta.label}`}
+            title={meta.hint}
+            className={cn('w-9 gap-0.5', className)}
+          >
             <SubagentDisplayIcon value={value} className="size-4" />
             <ChevronDown className="size-2.5 text-fg-4" />
           </Button>

package/src/components/agent/TranscriptItemView.tsx

@@ -1,5 +1,6 @@
 import type { MessageAttachment } from '@workerdeck/protocol'
-import type { TranscriptItem } from '@workerdeck/react'
+import { useEffect, useState } from 'react'
+import type { ShellItem, TranscriptItem } from '@workerdeck/react'
 import { cn } from '../../lib/utils.ts'
 import { compactionText, formatCost, formatDuration, formatRelativeTime } from '../../lib/format.ts'
 import { FileCard } from './FileCard.tsx'
@@ -11,6 +12,8 @@ import { ToolCallCard } from './ToolCallCard.tsx'
 import { Row } from '../terminal/row.tsx'
 import { TerminalItemView } from '../terminal/TerminalTranscript.tsx'
 import { peerLabel } from '../terminal/items.tsx'
+import { useShellActions } from './shell-actions.tsx'
+import { shellBodyLines, shellFailed, shellFooterText, shellLabel, shellStatusText } from '../terminal/shell-row.ts'
 
 function TurnResultRow({ item }: { item: Extract<TranscriptItem, { kind: 'turn_result' }> }) {
   return (
@@ -107,12 +110,82 @@ export function TranscriptItemView({
     case 'file_delivered': {
       return <FileCard item={item} href={fileUrl?.(item.path)} />
     }
+    case 'shell': {
+      return <ShellCard item={item} />
+    }
     default: {
       return null
     }
   }
 }
 
+function ShellCard({ item }: { item: ShellItem }) {
+  const [open, setOpen] = useState(false)
+  const actions = useShellActions()
+  const running = item.shell.status === 'running'
+  const failed = shellFailed(item)
+  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])
+
+  return (
+    <div data-slot="shell" className="overflow-hidden rounded-md border border-border bg-surface">
+      <div className="flex items-center gap-2 px-3 py-1.5">
+        <span className="font-mono text-label text-[var(--wd-shell-accent)]">$</span>
+        <button
+          type="button"
+          aria-expanded={open}
+          className="min-w-0 flex-1 truncate text-left font-mono text-label text-fg-1"
+          onClick={() => {
+            const next = !open
+            setOpen(next)
+            if (next && item.truncated && item.expanded === undefined && !item.missing) {
+              void actions.loadOutput(shellId)
+            }
+          }}
+        >
+          {shellLabel(item)}
+        </button>
+        <span className={cn('shrink-0 text-label', failed ? 'text-danger' : 'text-fg-4')}>{shellStatusText(item)}</span>
+        {actions.open ? (
+          <button
+            type="button"
+            aria-label="Open terminal"
+            title="Open terminal"
+            className="shrink-0 text-label text-fg-3 hover:text-fg-1"
+            onClick={() => actions.open?.(shellId)}
+          >
+            ⤢
+          </button>
+        ) : null}
+        {running ? (
+          <button
+            type="button"
+            aria-label="Kill this shell"
+            className="shrink-0 text-label text-fg-3"
+            onClick={() => void actions.kill(shellId)}
+          >
+            ✕
+          </button>
+        ) : null}
+      </div>
+      {lines.length > 0 ? (
+        <pre className="overflow-x-auto border-t border-border px-3 py-2 font-mono text-label whitespace-pre-wrap text-fg-2">
+          {lines.join('\n')}
+        </pre>
+      ) : null}
+      {footer ? <div className="px-3 pb-2 text-label text-fg-4">{footer}</div> : null}
+    </div>
+  )
+}
+
 function CompactionRow({ item }: { item: Extract<TranscriptItem, { kind: 'compaction' }> }) {
   return (
     <div data-slot="compaction" className="flex items-center gap-2 py-1">

package/src/components/agent/scrubber-marks.ts

@@ -3,7 +3,7 @@ import { formatCost, formatDuration, toolInputPreview } from '../../lib/format.t
 import { parentOf } from '../terminal/blocks.ts'
 
 export type Lane = 'l' | 'r' | 'f'
-export type MarkKind = 'user' | 'subagent' | 'turn' | 'turnFailed' | 'toolFailed' | 'error' | 'approval' | 'recap' | 'bookmark'
+export type MarkKind = 'user' | 'subagent' | 'shell' | 'turn' | 'turnFailed' | 'toolFailed' | 'error' | 'approval' | 'recap' | 'bookmark'
 
 export type Mark = {
   kind: MarkKind
@@ -32,6 +32,7 @@ export function nearestMember(cluster: Cluster, y: number): Mark | undefined {
 export const LANE: Record<MarkKind, Lane> = {
   user: 'l',
   subagent: 'l',
+  shell: 'l',
   turn: 'r',
   turnFailed: 'r',
   toolFailed: 'r',
@@ -50,12 +51,14 @@ export const LOUDNESS: Record<MarkKind, number> = {
   turn: 2,
   bookmark: 1,
   subagent: 1,
+  shell: 1,
   recap: 0,
 }
 
 export const KIND_NAME: Record<MarkKind, string> = {
   user: 'you',
   subagent: 'sub-agent',
+  shell: 'shell',
   turn: 'response · turn end',
   turnFailed: 'turn failed',
   toolFailed: 'tool failed',
@@ -79,6 +82,9 @@ export 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)})`
     }
@@ -139,6 +145,8 @@ export function buildMarks(
       closeSegment()
     } else if (item.kind === 'notice' && item.level === 'error') {
       marks.push({ kind: 'error', itemIndex: index })
+    } else if (item.kind === 'shell') {
+      marks.push({ kind: 'shell', itemIndex: index })
     } else if (
       item.kind === 'tool_call' &&
       parentOf(item) === frameParentId &&

package/src/components/agent/shell-actions.tsx

@@ -0,0 +1,25 @@
+import { createContext, useContext, type ReactNode } from 'react'
+
+export type ShellActions = {
+  loadOutput: (shellId: string) => Promise<boolean>
+  verify: (shellId: string) => Promise<boolean>
+  kill: (shellId: string) => Promise<boolean>
+  // Drill in to the shell's terminal. Absent when the host has no frame to open one in.
+  open?: (shellId: string) => void
+}
+
+const NOOP: ShellActions = {
+  loadOutput: async () => false,
+  verify: async () => false,
+  kill: async () => false,
+}
+
+const ShellActionsContext = createContext<ShellActions>(NOOP)
+
+export function ShellActionsProvider({ value, children }: { value: ShellActions | undefined; children: ReactNode }) {
+  return <ShellActionsContext.Provider value={value ?? NOOP}>{children}</ShellActionsContext.Provider>
+}
+
+export function useShellActions(): ShellActions {
+  return useContext(ShellActionsContext)
+}