@workerdeck/ui 0.9.0 → 0.12.0

package/src/components/agent/Response.tsx

@@ -1,6 +1,131 @@
 import { memo } from 'react'
 import { Streamdown } from 'streamdown'
 import { cn } from '../../lib/utils.ts'
+import { useLines } from './transcript-variant.tsx'
+
+/**
+ * Markdown on a terminal's grid.
+ *
+ * Prose defaults give every block its own rhythm — a heading is bigger, a list
+ * item is looser, an inline `code` chip is padded taller than the line it sits
+ * in — and the result is text that visibly breathes at different rates as you
+ * scroll. A terminal has exactly one line height and one type size, and that
+ * uniformity is most of what makes it readable at a glance.
+ *
+ * So: every line 1.25rem, every block flush, and one blank line (1.25rem, i.e.
+ * exactly one row) between blocks. Headings keep their weight but lose their
+ * size. Inline code keeps a background — it still has to be distinguishable —
+ * but no vertical padding, because that is what pushes a line off the grid.
+ */
+const TERMINAL_PROSE = [
+  'text-body-sm leading-5',
+  '[&_*]:leading-5',
+  // Block rhythm: nothing has its own margins, and siblings are one row apart.
+  // `!` throughout because these fight the renderer's own utilities, and some of
+  // those (`space-y-*`, which is a `> * + *` rule) outrank a plain descendant
+  // selector — a list would otherwise keep its half-row gaps while every other
+  // block snapped to the grid.
+  '[&_p]:my-0! [&_pre]:my-0! [&_blockquote]:my-0! [&_table]:my-0!',
+  '[&_h1]:my-0! [&_h2]:my-0! [&_h3]:my-0! [&_h4]:my-0! [&_h5]:my-0! [&_h6]:my-0!',
+  '[&>*+*]:mt-5',
+  // Lists are rows, not paragraphs: no margin anywhere in them, and no
+  // inter-item spacing from a `space-y` on the list itself.
+  '[&_ul]:my-0! [&_ol]:my-0! [&_li]:my-0! [&_li>p]:my-0!',
+  '[&_li+li]:mt-0! [&_ul_ul]:mt-0! [&_ul_ol]:mt-0! [&_ol_ul]:mt-0! [&_ol_ol]:mt-0!',
+  '[&_li]:py-0! [&_ul]:py-0! [&_ol]:py-0!',
+  // Markers on their own column, at the width the marker actually is — the
+  // indent a terminal (and the markdown source) uses, not a typographic one.
+  // `ch` is the unit because this variant runs in a monospace face: `• ` is two
+  // cells, `1. ` is three, so the text starts exactly where it would in the raw
+  // document and a wrapped line hangs under it instead of under the bullet.
+  // Nesting then costs one marker width per level, which is the 2-space step.
+  // `list-outside` is the load-bearing half: the renderer marks lists `inside`,
+  // where the marker joins the text flow — so the indent moves the bullet too
+  // (the list sits a marker-width right of the paragraph above it) and a wrapped
+  // line runs back under the bullet instead of hanging under its own text.
+  '[&_ul]:list-outside! [&_ol]:list-outside!',
+  '[&_ul]:pl-[2ch]! [&_ol]:pl-[3ch]! [&_li]:pl-0!',
+  // Headings are weight, not size — a terminal has one type size.
+  '[&_h1]:text-body-sm [&_h2]:text-body-sm [&_h3]:text-body-sm',
+  '[&_h4]:text-body-sm [&_h5]:text-body-sm [&_h6]:text-body-sm',
+  '[&_h1]:font-semibold [&_h2]:font-semibold [&_h3]:font-semibold',
+  '[&_h4]:font-semibold [&_h5]:font-semibold [&_h6]:font-semibold',
+  '[&_blockquote]:border-l [&_blockquote]:border-border [&_blockquote]:pl-2',
+  // Inline code only (`:not(pre) > code`) — fenced blocks keep their own box.
+  // Horizontal padding is free; vertical padding is what pushes a line off grid.
+  '[&_:not(pre)>code]:rounded-none [&_:not(pre)>code]:px-1! [&_:not(pre)>code]:py-0!',
+  '[&_:not(pre)>code]:text-body-sm [&_:not(pre)>code]:leading-5! [&_:not(pre)>code]:text-fg-1',
+  '[&_th]:py-0! [&_td]:py-0!',
+  // The renderer's fenced-code card: rounded frame, its own header strip, a
+  // second rounded frame inside it, and a floating pill for the buttons. Four
+  // boxes around what is, in a terminal, a band of dim text. Flattened to
+  // exactly that — the band keeps a background so a block still reads as code,
+  // and the actions keep their top-right corner but lose the pill.
+  '[&_[data-streamdown=code-block]]:my-0! [&_[data-streamdown=code-block]]:gap-0!',
+  '[&_[data-streamdown=code-block]]:rounded-none! [&_[data-streamdown=code-block]]:border-0!',
+  '[&_[data-streamdown=code-block]]:bg-transparent! [&_[data-streamdown=code-block]]:p-0!',
+  // The language strip costs a whole row to say what the code already shows, and
+  // the actions cost another. Both go: the block is the band, and the buttons
+  // float over its top-right corner, appearing on hover or keyboard focus.
+  '[&_[data-streamdown=code-block]]:relative!',
+  '[&_[data-streamdown=code-block-header]]:hidden!',
+  '[&_div:has(>[data-streamdown=code-block-actions])]:absolute! [&_div:has(>[data-streamdown=code-block-actions])]:top-0!',
+  '[&_div:has(>[data-streamdown=code-block-actions])]:right-0! [&_div:has(>[data-streamdown=code-block-actions])]:mt-0!',
+  '[&_div:has(>[data-streamdown=code-block-actions])]:h-5! [&_div:has(>[data-streamdown=code-block-actions])]:opacity-0!',
+  '[&_div:has(>[data-streamdown=code-block-actions])]:transition-opacity',
+  '[&_[data-streamdown=code-block]:hover_div:has(>[data-streamdown=code-block-actions])]:opacity-100!',
+  '[&_[data-streamdown=code-block]:focus-within_div:has(>[data-streamdown=code-block-actions])]:opacity-100!',
+  '[&_[data-streamdown=code-block-actions]]:rounded-none! [&_[data-streamdown=code-block-actions]]:border-0!',
+  '[&_[data-streamdown=code-block-actions]]:bg-code-bg! [&_[data-streamdown=code-block-actions]]:px-1!',
+  '[&_[data-streamdown=code-block-actions]]:py-0! [&_[data-streamdown=code-block-actions]]:gap-1!',
+  '[&_[data-streamdown=code-block-actions]]:backdrop-blur-none!',
+  '[&_[data-streamdown=code-block-body]]:rounded-none! [&_[data-streamdown=code-block-body]]:border-0!',
+  '[&_[data-streamdown=code-block-body]]:bg-code-bg! [&_[data-streamdown=code-block-body]]:px-2!',
+  '[&_[data-streamdown=code-block-body]]:py-0! [&_[data-streamdown=code-block-body]]:text-body-sm!',
+  // The action buttons' hit areas, on the grid like everything else.
+  '[&_[data-streamdown=code-block-copy-button]]:p-0! [&_[data-streamdown=code-block-download-button]]:p-0!',
+  // Tables come in a frame of their own, plus a controls row above them and a
+  // second frame around the scroller — three boxes and a blank line to hold
+  // three buttons. Same treatment: the table is the content, the buttons float
+  // over its top-right on hover. The controls row is the child that has no
+  // `<table>` in it, which is also how it knows to disappear when the renderer
+  // draws no controls at all.
+  '[&_[data-streamdown=table-wrapper]]:rounded-none! [&_[data-streamdown=table-wrapper]]:border-0!',
+  '[&_[data-streamdown=table-wrapper]]:my-0! [&_[data-streamdown=table-wrapper]]:bg-transparent!',
+  '[&_[data-streamdown=table-wrapper]]:relative! [&_[data-streamdown=table-wrapper]]:gap-0!',
+  '[&_[data-streamdown=table-wrapper]]:p-0!',
+  '[&_[data-streamdown=table-wrapper]>div:not(:has(table))]:absolute! [&_[data-streamdown=table-wrapper]>div:not(:has(table))]:top-0!',
+  '[&_[data-streamdown=table-wrapper]>div:not(:has(table))]:right-0! [&_[data-streamdown=table-wrapper]>div:not(:has(table))]:z-10!',
+  '[&_[data-streamdown=table-wrapper]>div:not(:has(table))]:opacity-0! [&_[data-streamdown=table-wrapper]>div:not(:has(table))]:bg-code-bg!',
+  '[&_[data-streamdown=table-wrapper]>div:not(:has(table))]:px-1! [&_[data-streamdown=table-wrapper]>div:not(:has(table))]:transition-opacity',
+  '[&_[data-streamdown=table-wrapper]:hover>div:not(:has(table))]:opacity-100!',
+  '[&_[data-streamdown=table-wrapper]:focus-within>div:not(:has(table))]:opacity-100!',
+  '[&_[data-streamdown=table-wrapper]>div:has(table)]:rounded-none! [&_[data-streamdown=table-wrapper]>div:has(table)]:border-0!',
+  '[&_[data-streamdown=table-wrapper]>div:has(table)]:bg-transparent!',
+].join(' ')
+
+/**
+ * The controls' icons as characters.
+ *
+ * The renderer draws its copy/download affordances as line-art SVGs, which next
+ * to monospace text read as buttons from another application. These are the
+ * glyphs a terminal would use — and they inherit the surrounding font, so they
+ * sit on the same grid as the code they belong to.
+ */
+const glyphIcon = (glyph: string) =>
+  function GlyphIcon({ className }: { className?: string }) {
+    return (
+      <span aria-hidden className={cn('font-mono text-body-sm leading-5', className)}>
+        {glyph}
+      </span>
+    )
+  }
+
+const TERMINAL_ICONS = {
+  DownloadIcon: glyphIcon('⤓'),
+  CopyIcon: glyphIcon('⧉'),
+  CheckIcon: glyphIcon('✓'),
+}
 
 export interface ResponseProps {
   children: string
@@ -13,13 +138,16 @@ export interface ResponseProps {
  * highlighted with shiki (dual theme follows [data-theme] through the dark: variant). */
 export const Response = memo(
   function Response({ children, streaming, className }: ResponseProps) {
+    const lines = useLines()
     return (
       <Streamdown
         mode={streaming ? 'streaming' : 'static'}
         parseIncompleteMarkdown={streaming}
         shikiTheme={['github-light', 'github-dark']}
+        icons={lines ? TERMINAL_ICONS : undefined}
         className={cn(
           'size-full [&>*:first-child]:mt-0 [&>*:last-child]:mb-0',
+          lines && TERMINAL_PROSE,
           className,
         )}>
         {children}

package/src/components/agent/SessionBrowser.tsx

@@ -0,0 +1,428 @@
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { Pencil, Search, Trash2, X } from 'lucide-react'
+import {
+  STATE_LABELS,
+  STATE_ORDER,
+  adaptersOf,
+  clearFilters,
+  filterRows,
+  groupRows,
+  hasFacetFilter,
+  sessionLabel,
+  subsetSummary,
+} from '@workerdeck/protocol'
+import type {
+  GroupBy,
+  SessionRow,
+  SessionState,
+  SortBy,
+  ViewConfig,
+  WorkspaceScope,
+} from '@workerdeck/protocol'
+import { Badge } from '../ui/Badge.tsx'
+import { Button } from '../ui/Button.tsx'
+import { Input } from '../ui/Input.tsx'
+import { Select, SelectContent, SelectItem, SelectItemText, SelectTrigger, SelectValue } from '../ui/Select.tsx'
+import { cn } from '../../lib/utils.ts'
+import { formatCost, formatRelativeTime } from '../../lib/format.ts'
+import { STATUS_META } from './status.ts'
+
+/**
+ * A sessions list with the affordances a list of thirty needs: search, facets,
+ * grouping, sorting, unread counts, and one honest line about what is hidden.
+ *
+ * The *rules* are `@workerdeck/protocol`'s (`filterRows`/`groupRows`/
+ * `subsetSummary`), not this component's — the VS Code sidebar renders the same
+ * model with workbench chrome, its activity-bar badge counts the same rows this
+ * would show, and iOS mirrors them in Swift. What lives here is the styled
+ * rendering of that model, so a host that wants the dashboard's look gets it
+ * without reimplementing the model behind it.
+ *
+ * `SessionList` remains beside this for the plain case (a fixed set of rows, no
+ * controls); this is what you reach for when the list is the screen.
+ */
+
+export interface SessionBrowserProps {
+  rows: SessionRow[]
+  config: ViewConfig
+  onConfigChange: (config: ViewConfig) => void
+  /** The host's own folders, if it has such a notion. Absent — a dashboard, a
+   * phone — makes the scope filter genuinely inert rather than empty. */
+  scope?: WorkspaceScope
+  activeId?: string
+  onSelect?: (row: SessionRow) => void
+  onDelete?: (row: SessionRow) => void
+  /**
+   * Rename, from the row's pencil. Empty string restores the derived title. A
+   * gateway edit (`PATCH /sessions/:id`), never a local override — every client
+   * should see the same name. Omit to make titles read-only.
+   *
+   * A hover affordance rather than the extension's double-click-the-title,
+   * because here a single click on the row navigates: the *first* click of a
+   * double-click would have already left the page.
+   */
+  onRename?: (row: SessionRow, title: string) => void
+  /** Rendered when nothing at all exists (as opposed to nothing matching). */
+  emptyState?: React.ReactNode
+  className?: string
+}
+
+export function SessionBrowser({
+  rows,
+  config,
+  onConfigChange,
+  scope,
+  activeId,
+  onSelect,
+  onDelete,
+  onRename,
+  emptyState,
+  className,
+}: SessionBrowserProps) {
+  const visible = useMemo(() => filterRows(rows, config, scope), [rows, config, scope])
+  const groups = useMemo(() => groupRows(visible, config), [visible, config])
+  const subset = subsetSummary(config, scope, visible.length, rows.length)
+  // Derived, not enumerated: a new engine or a new gateway needs no change here,
+  // and a facet with one possible value is not a choice worth showing.
+  const adapters = useMemo(() => adaptersOf(rows), [rows])
+  const gateways = useMemo(() => {
+    const seen = new Map<string, string>()
+    for (const row of rows) seen.set(row.hostId, row.hostName)
+    return [...seen].map(([id, name]) => ({ id, name }))
+  }, [rows])
+
+  const set = (patch: Partial<ViewConfig>) => onConfigChange({ ...config, ...patch })
+
+  return (
+    <div data-slot='session-browser' className={cn('flex flex-col gap-3', className)}>
+      <div className='flex flex-wrap items-center gap-2'>
+        <div className='relative min-w-48 flex-1'>
+          <Search className='pointer-events-none absolute top-1/2 left-2.5 size-3.5 -translate-y-1/2 text-fg-4' />
+          <Input
+            value={config.search}
+            onChange={(e) => set({ search: e.target.value })}
+            placeholder='Search sessions'
+            aria-label='Search sessions'
+            className='pl-8'
+          />
+        </div>
+        <FacetSelect
+          label='State'
+          value={config.states}
+          options={STATE_ORDER.map((s) => ({ value: s, label: STATE_LABELS[s] }))}
+          onChange={(states) => set({ states: states as SessionState[] })}
+        />
+        {adapters.length > 1 ? (
+          <FacetSelect
+            label='Engine'
+            value={config.adapters}
+            options={adapters.map((a) => ({ value: a, label: a }))}
+            onChange={(adapters) => set({ adapters })}
+          />
+        ) : null}
+        {gateways.length > 1 ? (
+          <FacetSelect
+            label='Gateway'
+            value={config.gateways}
+            options={gateways.map((g) => ({ value: g.id, label: g.name }))}
+            onChange={(gateways) => set({ gateways })}
+          />
+        ) : null}
+        <OneOfSelect
+          label='Group'
+          value={config.groupBy}
+          options={[
+            { value: 'none', label: 'No grouping' },
+            { value: 'state', label: 'By state' },
+            { value: 'adapter', label: 'By engine' },
+            ...(gateways.length > 1 ? [{ value: 'gateway' as const, label: 'By gateway' }] : []),
+          ]}
+          onChange={(groupBy) => set({ groupBy: groupBy as GroupBy })}
+        />
+        <OneOfSelect
+          label='Sort'
+          value={config.sortBy}
+          options={[
+            { value: 'recent', label: 'Recent' },
+            { value: 'name', label: 'Name' },
+            { value: 'state', label: 'State' },
+            ...(gateways.length > 1 ? [{ value: 'gateway' as const, label: 'Gateway' }] : []),
+          ]}
+          onChange={(sortBy) => set({ sortBy: sortBy as SortBy })}
+        />
+      </div>
+
+      {subset ? (
+        <div className='flex items-center gap-2 text-label text-fg-4'>
+          <span>
+            {subset.shown} of {subset.total}
+            {subset.causes.length ? ` · ${subset.causes.join(' · ')}` : null}
+          </span>
+          <button
+            type='button'
+            className='text-fg-3 underline underline-offset-2 hover:text-fg-1'
+            onClick={() => onConfigChange(clearFilters(config))}>
+            Show all
+          </button>
+        </div>
+      ) : null}
+
+      {rows.length === 0 ? (
+        (emptyState ?? <Empty>No sessions yet.</Empty>)
+      ) : visible.length === 0 ? (
+        // Two different dead ends, two different ways out. "Nothing matches" is
+        // a filter someone set; anything else is the state of the world.
+        <Empty>
+          {hasFacetFilter(config) ? (
+            <>
+              No sessions match.{' '}
+              <button
+                type='button'
+                className='underline underline-offset-2 hover:text-fg-1'
+                onClick={() => onConfigChange(clearFilters(config))}>
+                Clear filters
+              </button>
+            </>
+          ) : (
+            'No sessions here.'
+          )}
+        </Empty>
+      ) : (
+        <div className='flex flex-col gap-4'>
+          {groups.map((group) => (
+            <div key={group.key} className='flex flex-col gap-1'>
+              {config.groupBy !== 'none' && group.label ? (
+                <div className='flex items-baseline gap-2 px-2.5 text-label font-medium text-fg-4'>
+                  <span className='uppercase tracking-wide'>{group.label}</span>
+                  <span className='text-fg-4/70'>{group.rows.length}</span>
+                </div>
+              ) : null}
+              {group.rows.map((row) => (
+                <SessionRowItem
+                  key={`${row.hostId}:${row.info.id}`}
+                  row={row}
+                  active={row.info.id === activeId}
+                  showGateway={gateways.length > 1}
+                  onSelect={onSelect}
+                  onDelete={onDelete}
+                  onRename={onRename}
+                />
+              ))}
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+
+function Empty({ children }: { children: React.ReactNode }) {
+  return <div className='px-2.5 py-6 text-center text-body-sm text-fg-4'>{children}</div>
+}
+
+interface SessionRowItemProps {
+  row: SessionRow
+  active?: boolean
+  showGateway?: boolean
+  onSelect?: (row: SessionRow) => void
+  onDelete?: (row: SessionRow) => void
+  onRename?: (row: SessionRow, title: string) => void
+}
+
+function SessionRowItem({
+  row,
+  active,
+  showGateway,
+  onSelect,
+  onDelete,
+  onRename,
+}: SessionRowItemProps) {
+  const { info } = row
+  const meta = STATUS_META[info.status]
+  const [editing, setEditing] = useState(false)
+
+  return (
+    <div
+      data-slot='session-row'
+      data-active={active || undefined}
+      className={cn(
+        'group flex w-full items-center gap-2 rounded-md border border-transparent px-2.5 py-2 text-left transition-colors',
+        active ? 'border-border bg-surface' : 'hover:bg-surface-hover',
+      )}>
+      <div className='min-w-0 flex-1'>
+        <div className='flex items-center gap-2'>
+          {/* The editor replaces the link rather than sitting inside it — an
+              input nested in a button is invalid, and disabling the button to
+              protect the edit disables the field with it. */}
+          {editing && onRename ? (
+            <NameEditor
+              initial={info.title ?? ''}
+              onCommit={(title) => {
+                setEditing(false)
+                onRename(row, title)
+              }}
+              onCancel={() => setEditing(false)}
+            />
+          ) : (
+            <button
+              type='button'
+              onClick={() => onSelect?.(row)}
+              className='min-w-0 truncate text-left text-body-sm font-medium text-fg-1 outline-none'>
+              {sessionLabel(info)}
+            </button>
+          )}
+          <Badge variant={meta.variant} dot className='shrink-0'>
+            {meta.label}
+          </Badge>
+          {row.unseen > 0 ? (
+            // Transcript rows since this session was last on screen — the same
+            // unit the VS Code badge counts, because turns undercount badly.
+            <Badge variant='accent' className='shrink-0' title={`${row.unseen} new`}>
+              {row.unseen}
+            </Badge>
+          ) : null}
+        </div>
+        <button
+          type='button'
+          onClick={() => !editing && onSelect?.(row)}
+          className='mt-0.5 flex w-full items-center gap-2 text-left font-mono text-label text-fg-4 outline-none'>
+          <span className='truncate'>{info.cwd}</span>
+          {showGateway ? <span className='shrink-0'>{row.hostName}</span> : null}
+          {info.profile ? <span className='shrink-0'>@{info.profile}</span> : null}
+          <span className='shrink-0'>{formatCost(info.totalCostUsd)}</span>
+          <span className='shrink-0'>
+            {formatRelativeTime(info.lastActivityAt ?? info.createdAt)}
+          </span>
+        </button>
+      </div>
+      {onRename && !editing ? (
+        <Button
+          variant='ghost'
+          size='icon-sm'
+          aria-label='Rename session'
+          className='opacity-0 transition-opacity group-hover:opacity-100'
+          onClick={() => setEditing(true)}>
+          <Pencil className='size-3.5 text-fg-3' />
+        </Button>
+      ) : null}
+      {onDelete ? (
+        <Button
+          variant='ghost'
+          size='icon-sm'
+          aria-label='Close session'
+          className='opacity-0 transition-opacity group-hover:opacity-100'
+          onClick={() => onDelete(row)}>
+          <Trash2 className='size-3.5 text-fg-3' />
+        </Button>
+      ) : null}
+    </div>
+  )
+}
+
+/**
+ * Inline rename. Enter commits, Escape cancels, blur commits — but only a blur
+ * that is still inside this document: switching windows must not silently commit,
+ * nor kill the editor in the frame it opened.
+ */
+function NameEditor({
+  initial,
+  onCommit,
+  onCancel,
+}: {
+  initial: string
+  onCommit: (title: string) => void
+  onCancel: () => void
+}) {
+  const [value, setValue] = useState(initial)
+  const ref = useRef<HTMLInputElement>(null)
+  useEffect(() => {
+    ref.current?.select()
+  }, [])
+  return (
+    <input
+      ref={ref}
+      value={value}
+      autoFocus
+      aria-label='Session name'
+      // The row is a button; a click in here must not select the session.
+      onClick={(e) => e.stopPropagation()}
+      onChange={(e) => setValue(e.target.value)}
+      onBlur={() => (document.hasFocus() ? onCommit(value.trim()) : undefined)}
+      onKeyDown={(e) => {
+        if (e.key === 'Enter') onCommit(value.trim())
+        else if (e.key === 'Escape') onCancel()
+        e.stopPropagation()
+      }}
+      className='-my-0.5 min-w-0 flex-1 rounded-sm border border-ring bg-bg px-1 py-0.5 text-body-sm font-medium text-fg-1 outline-none'
+    />
+  )
+}
+
+/** A multi-select facet. Empty = no filter, which is why the trigger reads the
+ * facet's name rather than "All": nothing is being excluded. */
+function FacetSelect({
+  label,
+  value,
+  options,
+  onChange,
+}: {
+  label: string
+  value: string[]
+  options: { value: string; label: string }[]
+  onChange: (value: string[]) => void
+}) {
+  return (
+    <div className='flex items-center gap-1'>
+      <Select multiple value={value} onValueChange={(v) => onChange(v as string[])}>
+        <SelectTrigger aria-label={label} className='min-w-28'>
+          <SelectValue>
+            {value.length === 0
+              ? label
+              : value.length === 1
+                ? (options.find((o) => o.value === value[0])?.label ?? label)
+                : `${label} · ${value.length}`}
+          </SelectValue>
+        </SelectTrigger>
+        <SelectContent>
+          {options.map((option) => (
+            <SelectItem key={option.value} value={option.value}>
+              <SelectItemText>{option.label}</SelectItemText>
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+      {value.length > 0 ? (
+        <Button variant='ghost' size='icon-sm' aria-label={`Clear ${label}`} onClick={() => onChange([])}>
+          <X className='size-3 text-fg-4' />
+        </Button>
+      ) : null}
+    </div>
+  )
+}
+
+function OneOfSelect({
+  label,
+  value,
+  options,
+  onChange,
+}: {
+  label: string
+  value: string
+  options: readonly { value: string; label: string }[]
+  onChange: (value: string) => void
+}) {
+  return (
+    <Select value={value} onValueChange={(v) => onChange(v as string)}>
+      <SelectTrigger aria-label={label} className='min-w-28'>
+        <SelectValue>{options.find((o) => o.value === value)?.label ?? label}</SelectValue>
+      </SelectTrigger>
+      <SelectContent>
+        {options.map((option) => (
+          <SelectItem key={option.value} value={option.value}>
+            <SelectItemText>{option.label}</SelectItemText>
+          </SelectItem>
+        ))}
+      </SelectContent>
+    </Select>
+  )
+}

package/src/components/agent/SessionEmptyState.tsx

@@ -0,0 +1,65 @@
+import { AtSign, MessageSquareText, SlashSquare, Sparkles, Terminal } from 'lucide-react'
+import { cn } from '../../lib/utils.ts'
+
+export interface SessionEmptyStateProps {
+  cwd?: string
+  /** Whether `/command` completion is live yet — the CLI reports its commands a
+   * beat after the session starts, and promising a feature that isn't wired up
+   * yet is worse than not mentioning it. */
+  hasCommands?: boolean
+  /** Whether the engine has reported skills the `/` popover can offer. Its own
+   * flag, not a variant of `hasCommands`: what `/` does differs — a command is
+   * submitted, a skill is typed for you to edit — and an engine can have one
+   * without the other. */
+  hasSkills?: boolean
+  /** Whether this gateway serves `@file` search for the session's directory. */
+  canBrowseFiles?: boolean
+  className?: string
+}
+
+/**
+ * What a session shows before it has said anything: where the agent is sitting,
+ * and what the composer accepts beyond prose.
+ *
+ * Every hint is conditional on the affordance actually existing — an engine
+ * without slash commands, or a gateway without host files, is not told about
+ * them. Deliberately no project name (the header already carries it) and no
+ * brand mark (its geometry is inlined in several places already and they are
+ * meant to stay identical).
+ */
+export function SessionEmptyState({
+  cwd,
+  hasCommands,
+  hasSkills,
+  canBrowseFiles,
+  className,
+}: SessionEmptyStateProps) {
+  const hints = [
+    { icon: MessageSquareText, text: 'Tell the agent what to do.' },
+    // Two keys, two hints — they are different features, not two spellings of
+    // one. `$` is codex's own sigil for skills; `/` stays the CLI's commands.
+    ...(hasCommands ? [{ icon: SlashSquare, text: 'Type / for the CLI’s slash commands.' }] : []),
+    ...(hasSkills
+      ? [{ icon: Sparkles, text: 'Type $ to draft a message for one of the agent’s skills.' }]
+      : []),
+    ...(canBrowseFiles
+      ? [{ icon: AtSign, text: 'Type @ to search this project’s files.' }]
+      : []),
+  ]
+  return (
+    <div className={cn('flex flex-col items-center gap-4 py-10', className)}>
+      <div className='flex size-12 items-center justify-center rounded-xl bg-surface text-fg-3'>
+        <Terminal className='size-5' />
+      </div>
+      {cwd ? <p className='max-w-full truncate font-mono text-label text-fg-4'>{cwd}</p> : null}
+      <ul className='w-full max-w-sm divide-y divide-border overflow-hidden rounded-lg bg-surface'>
+        {hints.map((hint) => (
+          <li key={hint.text} className='flex items-center gap-3 px-3.5 py-2.5'>
+            <hint.icon className='size-4 shrink-0 text-fg-4' />
+            <span className='text-body-sm text-fg-3'>{hint.text}</span>
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}