@workerdeck/ui 3.0.1 → 3.1.0

package/src/components/agent/scrubber-peek.tsx

@@ -0,0 +1,122 @@
+import type { ReactNode } from 'react'
+import type { PermissionRequest } from '@workerdeck/protocol'
+import type { TranscriptItem } from '@workerdeck/react'
+import { toolInputPreview } from '../../lib/format.ts'
+import { permissionPromptModel } from '../../lib/permission-prompt.ts'
+import { doneLine, excerpt, KIND_NAME, type Cluster, type Mark } from './scrubber-marks.ts'
+
+export type PeekSkin = {
+  excerptClass: string
+  muted: string
+  danger: string
+  glyph: string
+  text?: string
+  strong?: string
+  detail?: string
+  answerGlyph?: string
+}
+
+export const CARD_PEEK: PeekSkin = { excerptClass: 'wd-scrub-ex', muted: 'muted', danger: 'danger', glyph: 'muted', detail: 'muted' }
+
+export const TERMINAL_PEEK: PeekSkin = {
+  excerptClass: 'term-scrub-ex',
+  muted: 'faint',
+  danger: 'red',
+  glyph: 'dim',
+  text: 'fg',
+  strong: 'bright',
+  detail: 'fg',
+  answerGlyph: '● ',
+}
+
+export interface PeekInput {
+  cluster: Cluster
+  first: Mark | undefined
+  items: readonly TranscriptItem[]
+  pendingApprovals: readonly PermissionRequest[]
+  recapLabel?: string
+}
+
+export function peekContent({ cluster, first, items, pendingApprovals, recapLabel }: PeekInput, skin: PeekSkin): ReactNode {
+  const more = cluster.marks.length > 1 ? ` · ${cluster.marks.length} marks` : ''
+  const kind = first?.kind ?? cluster.kind
+  return (
+    <>
+      <div data-tone={skin.muted}>
+        {KIND_NAME[kind]}
+        {more}
+      </div>
+      {cluster.kind === 'approval'
+        ? approvalBody(pendingApprovals[0], skin)
+        : kind === 'recap'
+          ? recapBody(recapLabel, skin)
+          : markBody(first, items, skin)}
+    </>
+  )
+}
+
+function approvalBody(request: PermissionRequest | undefined, skin: PeekSkin): ReactNode {
+  if (!request) {
+    return null
+  }
+  return (
+    <>
+      <div data-tone={skin.strong}>{permissionPromptModel(request).heading}</div>
+      <div className={skin.excerptClass} data-tone={skin.detail}>
+        {`${request.displayName ?? request.toolName}(${toolInputPreview(request.input)})`}
+      </div>
+    </>
+  )
+}
+
+function recapBody(label: string | undefined, skin: PeekSkin): ReactNode {
+  return label === undefined ? null : <div data-tone={skin.muted}>※ {label}</div>
+}
+
+function markBody(first: Mark | undefined, items: readonly TranscriptItem[], skin: PeekSkin): ReactNode {
+  if (!first) {
+    return null
+  }
+  const item = items[first.itemIndex]
+  if (first.kind === 'turn' || first.kind === 'turnFailed') {
+    const turn = first.turnIndex === undefined ? undefined : items[first.turnIndex]
+    return (
+      <>
+        {item?.kind === 'assistant_text' ? (
+          <div className={skin.excerptClass} data-tone={skin.text}>
+            {skin.answerGlyph ? <span data-tone={skin.glyph}>{skin.answerGlyph}</span> : null}
+            {item.text}
+          </div>
+        ) : null}
+        {turn?.kind === 'turn_result' ? (
+          <>
+            <div data-tone={turn.isError ? skin.danger : skin.muted}>{doneLine(turn)}</div>
+            {turn.errors?.map((message, index) => (
+              <div key={index} data-tone={skin.danger}>
+                {message}
+              </div>
+            ))}
+          </>
+        ) : null}
+      </>
+    )
+  }
+  if (!item) {
+    return null
+  }
+  const failure =
+    first.kind === 'toolFailed' && item.kind === 'tool_call' ? item.result?.text.split('\n').find((line) => line.trim() !== '') : undefined
+  return (
+    <>
+      <div className={skin.excerptClass} data-tone={first.kind === 'error' || first.kind === 'toolFailed' ? skin.danger : skin.text}>
+        {first.kind === 'user' ? <span data-tone={skin.glyph}>{'❯ '}</span> : null}
+        {excerpt(item)}
+      </div>
+      {failure ? (
+        <div className={skin.excerptClass} data-tone={skin.danger}>
+          {failure}
+        </div>
+      ) : null}
+    </>
+  )
+}

package/src/components/agent/session-panel-providers.tsx

@@ -0,0 +1,41 @@
+import type { ReactNode } from 'react'
+import { FileLinkProvider, type FileLinkHandle } from '../terminal/file-link.tsx'
+import { ShellActionsProvider, type ShellActions } from './shell-actions.tsx'
+import { ToolResultFetchProvider, type ToolResultFetcher } from './tool-result-fetch.tsx'
+import { ToolResultImageProvider, type ToolResultImageLoader } from './tool-result-image.tsx'
+import { ToolTitleProvider } from './tool-titles.tsx'
+import { TranscriptVariantProvider, type TranscriptVariant } from './transcript-variant.tsx'
+
+type SessionPanelProvidersProps = {
+  variant: TranscriptVariant
+  fileLinks: FileLinkHandle | undefined
+  loadFullResult: ToolResultFetcher
+  shellActions: ShellActions
+  toolTitles: Record<string, string> | undefined
+  resultImages: ToolResultImageLoader
+  children: ReactNode
+}
+
+export function SessionPanelProviders({
+  variant,
+  fileLinks,
+  loadFullResult,
+  shellActions,
+  toolTitles,
+  resultImages,
+  children,
+}: SessionPanelProvidersProps) {
+  return (
+    <TranscriptVariantProvider value={variant}>
+      <FileLinkProvider value={fileLinks}>
+        <ToolResultFetchProvider value={loadFullResult}>
+          <ShellActionsProvider value={shellActions}>
+            <ToolTitleProvider value={toolTitles}>
+              <ToolResultImageProvider value={resultImages}>{children}</ToolResultImageProvider>
+            </ToolTitleProvider>
+          </ShellActionsProvider>
+        </ToolResultFetchProvider>
+      </FileLinkProvider>
+    </TranscriptVariantProvider>
+  )
+}

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

@@ -1,4 +1,7 @@
-import { createContext, useContext, type ReactNode } from 'react'
+import { createContext, useContext, useEffect, type ReactNode } from 'react'
+import type { ShellItem } from '@workerdeck/react'
+import { AgentWriteAction, BookmarkAction, CopyAction, KillShellAction, OpenShellAction } from '../terminal/affordances.tsx'
+import { shellAgentWriteLabel, shellGrantable } from '../terminal/shell-row.ts'
 
 export type ShellActions = {
   loadOutput: (shellId: string) => Promise<boolean>
@@ -25,3 +28,35 @@ export function ShellActionsProvider({ value, children }: { value: ShellActions
 export function useShellActions(): ShellActions {
   return useContext(ShellActionsContext)
 }
+
+// A row that still says running re-asks the gateway once, so a shell that died while nobody watched stops claiming it runs.
+export function useVerifyRunning(item: ShellItem): void {
+  const verify = useShellActions().verify
+  const running = item.shell.status === 'running'
+  const shellId = item.shell.id
+  useEffect(() => {
+    if (running) {
+      void verify(shellId)
+    }
+  }, [running, shellId, verify])
+}
+
+export function ShellItemActions({ item }: { item: ShellItem }) {
+  const actions = useShellActions()
+  const shellId = item.shell.id
+  return (
+    <>
+      {actions.open ? <OpenShellAction onOpen={() => actions.open?.(shellId)} /> : null}
+      {actions.agentWrite && shellGrantable(item.shell) ? (
+        <AgentWriteAction
+          granted={item.shell.agentWrite === true}
+          label={shellAgentWriteLabel(item.shell)}
+          onToggle={() => void actions.agentWrite?.(shellId, item.shell.agentWrite !== true)}
+        />
+      ) : null}
+      {item.shell.status === 'running' ? <KillShellAction onKill={() => void actions.kill(shellId)} /> : null}
+      <BookmarkAction id={item.id} />
+      <CopyAction text={item.shell.command} label="Copy command" />
+    </>
+  )
+}

package/src/components/agent/use-catch-up.ts

@@ -0,0 +1,20 @@
+import { useCallback, useState } from 'react'
+
+export type CatchUpMark = { itemCount: number; since?: number }
+
+type CatchUpState = { sessionId: string | undefined; mark: CatchUpMark | undefined; caughtUp: boolean }
+
+// The mark is the host's `unseen` as it stood when this session opened; later values are the host catching up, not news.
+export function useCatchUp(
+  sessionId: string | undefined,
+  unseen: CatchUpMark | undefined,
+): { mark: CatchUpMark | undefined; dismiss: () => void } {
+  const [held, setHeld] = useState<CatchUpState>({ sessionId, mark: unseen, caughtUp: false })
+  let current = held
+  if (held.sessionId !== sessionId) {
+    current = { sessionId, mark: unseen, caughtUp: false }
+    setHeld(current)
+  }
+  const dismiss = useCallback(() => setHeld((prev) => (prev.caughtUp ? prev : { ...prev, caughtUp: true })), [])
+  return { mark: current.caughtUp ? undefined : current.mark, dismiss }
+}

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

@@ -0,0 +1,88 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+export type FrameReveal = { toolUseId: string; nonce: number }
+
+export type FrameOptions = {
+  sessionId: string | undefined
+  // A host request to enter a frame; `id: undefined` withdraws it.
+  request?: { id: string | undefined; nonce: number }
+  // A host request to reveal a transcript row: it closes the frame without the return reveal, which would fight it.
+  reveal?: { nonce: number }
+  onChange?: (id: string | undefined) => void
+  // The transcript row leaving the frame reveals, so the reader lands where they left.
+  returnTo: (id: string) => string | undefined
+}
+
+export type Frame = {
+  id: string | undefined
+  enter: (id: string) => void
+  leave: () => void
+  returnReveal: FrameReveal | undefined
+}
+
+// The frame machine behind both the sub-agent and the shell takeover. The frame round-trips through
+// the host's URL (GOTCHAS "The sub-agent frame round-trips through the URL"): entry keys on the nonce
+// alone, and the report is deduped through a ref, so an echo of our own report is inert on arrival.
+export function useFrame({ sessionId, request, reveal, onChange, returnTo }: FrameOptions): Frame {
+  const [id, setId] = useState<string | undefined>(undefined)
+  const [returnReveal, setReturnReveal] = useState<FrameReveal | undefined>(undefined)
+  useEffect(() => {
+    setId(undefined)
+    setReturnReveal(undefined)
+  }, [sessionId])
+
+  const returnToRef = useRef(returnTo)
+  returnToRef.current = returnTo
+  const leave = useCallback(() => {
+    setId((current) => {
+      const toolUseId = current === undefined ? undefined : returnToRef.current(current)
+      if (toolUseId !== undefined) {
+        setReturnReveal({ toolUseId, nonce: Date.now() })
+      }
+      return undefined
+    })
+  }, [])
+
+  const requestNonce = request?.nonce
+  const requestId = request?.id
+  useEffect(() => {
+    if (requestId === undefined) {
+      leave()
+    } else {
+      setId(requestId)
+    }
+  }, [requestNonce])
+
+  const revealNonce = reveal?.nonce
+  useEffect(() => {
+    if (revealNonce !== undefined) {
+      setId(undefined)
+    }
+  }, [revealNonce])
+
+  useEffect(() => {
+    if (id === undefined) {
+      return
+    }
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === 'Escape' && !event.defaultPrevented) {
+        leave()
+      }
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [id, leave])
+
+  const onChangeRef = useRef(onChange)
+  onChangeRef.current = onChange
+  const reported = useRef<string | undefined>(undefined)
+  useEffect(() => {
+    if (reported.current === id) {
+      return
+    }
+    reported.current = id
+    onChangeRef.current?.(id)
+  }, [id])
+
+  return { id, enter: setId, leave, returnReveal }
+}

package/src/components/agent/use-host-image.ts

@@ -0,0 +1,81 @@
+import { useCallback, useEffect, useMemo } from 'react'
+import type { WorkerDeckClient } from '@workerdeck/client'
+import type { ProducedFileRef } from '@workerdeck/react'
+
+type HostImageStore = { cache: Map<string, Promise<string | undefined>>; urls: Set<string>; live: boolean }
+
+const IMAGE_MEDIA_TYPES: Record<string, string> = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+}
+
+// A definitive "no image" stays cached; a failed request does not, so a later render can ask again.
+export function useHostImage(
+  client: WorkerDeckClient,
+  sessionId: string | undefined,
+  producedFiles: Record<string, ProducedFileRef> | undefined,
+): (path: string) => Promise<string | undefined> {
+  const store = useMemo<HostImageStore>(() => ({ cache: new Map(), urls: new Set(), live: true }), [client, sessionId])
+  useEffect(() => {
+    store.live = true
+    return () => {
+      store.live = false
+      for (const url of store.urls) {
+        URL.revokeObjectURL(url)
+      }
+      store.urls.clear()
+      store.cache.clear()
+    }
+  }, [store])
+  return useCallback(
+    (path: string) => {
+      const produced = producedFiles?.[path]
+      const key = produced ? `produced:${produced.fileId}` : `fs:${path}`
+      const hit = store.cache.get(key)
+      if (hit) {
+        return hit
+      }
+      const request = produced && sessionId ? readProduced(client, sessionId, produced.fileId, store) : readHostImage(client, path)
+      const pending = request.catch(() => {
+        if (store.cache.get(key) === pending) {
+          store.cache.delete(key)
+        }
+        return undefined
+      })
+      store.cache.set(key, pending)
+      return pending
+    },
+    [client, sessionId, producedFiles, store],
+  )
+}
+
+async function readProduced(
+  client: WorkerDeckClient,
+  sessionId: string,
+  fileId: string,
+  store: HostImageStore,
+): Promise<string | undefined> {
+  const blob = await client.readProducedFile(sessionId, fileId)
+  if (blob.size === 0) {
+    return undefined
+  }
+  const url = URL.createObjectURL(blob)
+  if (!store.live) {
+    URL.revokeObjectURL(url)
+    throw new Error('host image store disposed')
+  }
+  store.urls.add(url)
+  return url
+}
+
+async function readHostImage(client: WorkerDeckClient, path: string): Promise<string | undefined> {
+  const file = await client.readHostFile(path)
+  if (file.encoding !== 'base64') {
+    return undefined
+  }
+  const mediaType = IMAGE_MEDIA_TYPES[path.slice(path.lastIndexOf('.') + 1).toLowerCase()]
+  return mediaType ? `data:${mediaType};base64,${file.content}` : undefined
+}

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

@@ -1,6 +1,7 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { useMemo, useRef } from 'react'
 import type { SessionInfo, ShellInfo } from '@workerdeck/protocol'
 import type { ShellItem, TranscriptItem } from '@workerdeck/react'
+import { useFrame } from './use-frame.ts'
 
 export type ShellFrameOptions = {
   sessionId: string | undefined
@@ -21,83 +22,24 @@ export type ShellFrame = {
   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 frame = useFrame({
+    sessionId,
+    request: openShell && { id: openShell.shellId, nonce: openShell.nonce },
+    reveal,
+    onChange: onShellChange,
+    returnTo: () => rowIdRef.current,
+  })
+  const shellId = frame.id
+
   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
@@ -107,5 +49,5 @@ export function useShellFrame(options: ShellFrameOptions): ShellFrame {
 
   const label = shell ? shell.label || shell.command.split('\n')[0] || 'shell' : 'shell'
 
-  return { shellId, enterShell: setShellId, leaveShell, returnReveal, shell, label }
+  return { shellId, enterShell: frame.enter, leaveShell: frame.leave, returnReveal: frame.returnReveal, shell, label }
 }

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

@@ -1,91 +1,27 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { useMemo } from 'react'
 import { subagentLabel, type SessionInfo } from '@workerdeck/protocol'
 import type { TranscriptItem } from '@workerdeck/react'
 import { subagentItems, type ToolCallItem } from '../terminal/blocks.ts'
+import { useFrame } from './use-frame.ts'
 
-// The sub-agent frame machine: which agent frame is on screen, how it is entered (a host
-// `openSubagent` request or a Task row in the transcript), how it is left (Escape, the strip's
-// Back, or the host withdrawing), and what the transcript reveals on the way out. The frame
-// round-trips through the host's URL - the anti-loop rules live in GOTCHAS ("The sub-agent
-// frame round-trips through the URL"); here they mean: entry keys on the nonce alone, and the
-// report is deduped through a ref, so an echo of our own report is inert on arrival.
 export function useSubagentFrame(options: {
   sessionId: string | undefined
   items: TranscriptItem[]
   session: SessionInfo | undefined
-  // Host request to reveal a transcript row; entering a frame must not eat a pending one.
   reveal?: { toolUseId: string; nonce: number }
-  // Host request to enter a frame; `toolUseId: undefined` withdraws it (Back/Forward).
   openSubagent?: { toolUseId: string; nonce: number }
   onSubagentChange?: (toolUseId: string | undefined) => void
 }) {
   const { sessionId, items, session, reveal, openSubagent, onSubagentChange } = options
 
-  const [subagentId, setSubagentId] = useState<string | undefined>(undefined)
-  const [returnReveal, setReturnReveal] = useState<{ toolUseId: string; nonce: number } | undefined>(undefined)
-  useEffect(() => {
-    setSubagentId(undefined)
-    setReturnReveal(undefined)
-  }, [sessionId])
-
-  // Leaving a frame reveals the Task row it came from, so the reader lands where they left.
-  const leaveSubagent = useCallback(() => {
-    setSubagentId((current) => {
-      if (current !== undefined) {
-        setReturnReveal({ toolUseId: current, nonce: Date.now() })
-      }
-      return undefined
-    })
-  }, [])
-
-  const openSubagentNonce = openSubagent?.nonce
-  const openSubagentId = openSubagent?.toolUseId
-  useEffect(() => {
-    if (openSubagentId === undefined) {
-      leaveSubagent()
-    } else {
-      setSubagentId(openSubagentId)
-    }
-    // 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
-  }, [openSubagentNonce])
-
-  // A reveal targets the root transcript, so it closes whatever frame is open - without the
-  // return reveal, which would fight the requested one.
-  const revealNonce = reveal?.nonce
-  useEffect(() => {
-    if (revealNonce === undefined) {
-      return
-    }
-    setSubagentId(undefined)
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [revealNonce])
-
-  useEffect(() => {
-    if (subagentId === undefined) {
-      return
-    }
-    const onKey = (event: KeyboardEvent) => {
-      if (event.key !== 'Escape' || event.defaultPrevented) {
-        return
-      }
-      leaveSubagent()
-    }
-    window.addEventListener('keydown', onKey)
-    return () => window.removeEventListener('keydown', onKey)
-  }, [subagentId, leaveSubagent])
-
-  const onSubagentChangeRef = useRef(onSubagentChange)
-  onSubagentChangeRef.current = onSubagentChange
-  const reportedSubagentId = useRef<string | undefined>(undefined)
-  useEffect(() => {
-    if (reportedSubagentId.current === subagentId) {
-      return
-    }
-    reportedSubagentId.current = subagentId
-    onSubagentChangeRef.current?.(subagentId)
-  }, [subagentId])
+  const frame = useFrame({
+    sessionId,
+    request: openSubagent && { id: openSubagent.toolUseId, nonce: openSubagent.nonce },
+    reveal,
+    onChange: onSubagentChange,
+    returnTo: (toolUseId) => toolUseId,
+  })
+  const subagentId = frame.id
 
   const frameItems = useMemo(() => (subagentId === undefined ? [] : subagentItems(items, subagentId)), [items, subagentId])
   const task = useMemo(
@@ -100,5 +36,13 @@ export function useSubagentFrame(options: {
     return record ? subagentLabel(record) : 'Sub-agent'
   }, [session, subagentId])
 
-  return { subagentId, enterSubagent: setSubagentId, leaveSubagent, returnReveal, frameItems, task, fallbackLabel }
+  return {
+    subagentId,
+    enterSubagent: frame.enter,
+    leaveSubagent: frame.leave,
+    returnReveal: frame.returnReveal,
+    frameItems,
+    task,
+    fallbackLabel,
+  }
 }