@workerdeck/ui 2.15.0 → 3.0.1

package/src/components/agent/tool-result-image.tsx

@@ -55,6 +55,46 @@ export function useToolResultImageSrc(ref: ToolResultImageRef): ToolResultImageS
   return state
 }
 
+export type HostImageLoader = (path: string) => Promise<string | undefined>
+
+const HostImageContext = createContext<HostImageLoader | undefined>(undefined)
+
+export function HostImageProvider({ value, children }: { value: HostImageLoader | undefined; children: ReactNode }) {
+  return <HostImageContext.Provider value={value}>{children}</HostImageContext.Provider>
+}
+
+export function useHostImageSrc(path: string | undefined, override?: HostImageLoader): ToolResultImageState {
+  const provided = useContext(HostImageContext)
+  const load = override ?? provided
+  const [state, setState] = useState<ToolResultImageState>({ failed: false })
+  useEffect(() => {
+    if (path === undefined) {
+      return
+    }
+    if (!load) {
+      setState({ failed: true })
+      return
+    }
+    let live = true
+    setState({ failed: false })
+    load(path)
+      .then((src) => {
+        if (live) {
+          setState({ src, failed: src === undefined })
+        }
+      })
+      .catch(() => {
+        if (live) {
+          setState({ failed: true })
+        }
+      })
+    return () => {
+      live = false
+    }
+  }, [load, path])
+  return state
+}
+
 const CACHE_BUDGET_BYTES = 64 * 1024 * 1024
 
 type Entry = { pending: Promise<string | undefined>; url?: string; bytes: number }

package/src/components/agent/transcript-variant.tsx

@@ -12,27 +12,9 @@ export function useTranscriptVariant(): TranscriptVariant {
   return useContext(VariantContext)
 }
 
-export type TranscriptDensity = 'comfortable' | 'compact'
-
-const DensityContext = createContext<TranscriptDensity>('comfortable')
-
-export function TranscriptDensityProvider({ value, children }: { value: TranscriptDensity; children: ReactNode }) {
-  return <DensityContext.Provider value={value}>{children}</DensityContext.Provider>
-}
-
-export function useTranscriptDensity(): TranscriptDensity {
-  return useContext(DensityContext)
-}
-
 export type TranscriptFont = 'sans' | 'mono'
 
-export const ROW_GAP: Record<TranscriptVariant, Record<TranscriptDensity, { className?: string; px: number }>> = {
-  terminal: {
-    comfortable: { className: 'term-row-gap', px: 18 },
-    compact: { className: 'term-row-gap', px: 18 },
-  },
-  cards: {
-    comfortable: { className: 'pt-4', px: 16 },
-    compact: { className: 'pt-2', px: 8 },
-  },
+export const ROW_GAP: Record<TranscriptVariant, { className?: string; px: number }> = {
+  terminal: { className: 'term-row-gap', px: 18 },
+  cards: { className: 'pt-5', px: 20 },
 }

package/src/components/prompt-area/use-prompt-area-keydown.ts

@@ -383,10 +383,12 @@ export function usePromptAreaKeydown({
         const launcher = triggers.find((t) => t.mode === 'launch' && t.char === e.key)
         const editor = editorRef.current
         if (launcher?.onActivate && editor) {
-          const cursorPos = getCursorOffset(editor)
-          if (cursorPos !== null) {
+          const caret = getCursorOffset(editor)
+          if (caret !== null) {
             const segments = readSegmentsFromDOM()
             const plainText = segmentsToPlainText(segments)
+            // An emptied editor keeps the browser's filler <br>: the reader drops it, the caret count does not.
+            const cursorPos = Math.min(caret, plainText.length)
             if (isValidTriggerPosition(plainText, cursorPos, launcher.position)) {
               e.preventDefault()
               launcher.onActivate({

package/src/components/terminal/PermissionPrompt.tsx

@@ -2,6 +2,7 @@ import { useState } from 'react'
 import type { PermissionRequest } from '@workerdeck/protocol'
 import { toolInputPreview } from '../../lib/format.ts'
 import { planFromRequest } from '../../lib/plan-request.ts'
+import { shellRequestLines, shellRequestPayload, shellRequestTitle } from '../../lib/shell-request.ts'
 import { TerminalDiff, previewPatch } from './diff.tsx'
 import { TerminalMarkdown } from './markdown.tsx'
 import { Choices, Hint, PromptInput, PromptTitle, Rule } from './prompt.tsx'
@@ -29,9 +30,14 @@ export function TerminalPermissionPrompt({ request, onApprove, onDeny, className
   }
 
   const plan = planFromRequest(request)
-  const patch = plan ? undefined : previewPatch(request.input)
-  const summary = plan ? '' : toolInputPreview(request.input)
-  const heading = plan ? 'Plan ready for review' : (request.displayName ?? request.title ?? 'Permission needed')
+  const shell = plan ? undefined : shellRequestPayload(request)
+  const patch = plan || shell ? undefined : previewPatch(request.input)
+  const summary = plan || shell ? '' : toolInputPreview(request.input)
+  const heading = plan
+    ? 'Plan ready for review'
+    : shell
+      ? shellRequestTitle(shell)
+      : (request.displayName ?? request.title ?? 'Permission needed')
   const subject = patch?.path ?? (summary || undefined)
 
   const reasonInput = denying ? (
@@ -82,6 +88,16 @@ export function TerminalPermissionPrompt({ request, onApprove, onDeny, className
           <Blank />
           <Rule dashed />
         </>
+      ) : shell ? (
+        <>
+          {shellRequestLines(shell).map((line, index) => (
+            <Row key={index} bold>
+              {line}
+            </Row>
+          ))}
+          <Blank />
+          <Rule dashed />
+        </>
       ) : patch ? (
         <>
           <TerminalDiff patch={patch} />
@@ -95,7 +111,7 @@ export function TerminalPermissionPrompt({ request, onApprove, onDeny, className
         </>
       ) : null}
       {request.decisionReason ? <Row tone="faint">{request.decisionReason}</Row> : null}
-      <Row>{plan ? 'Ready to implement this plan?' : (request.title ?? `Do you want to proceed?`)}</Row>
+      <Row>{plan ? 'Ready to implement this plan?' : shell ? 'Do you want to let it?' : (request.title ?? `Do you want to proceed?`)}</Row>
       <Choices
         label={heading}
         options={options}

package/src/components/terminal/TerminalTranscript.tsx

@@ -2,7 +2,7 @@ import { Fragment, useEffect, useMemo, useState } from 'react'
 import type { TranscriptItem, TranscriptState } from '@workerdeck/react'
 import { cn } from '../../lib/utils.ts'
 import type { TerminalAffordances } from './affordances.tsx'
-import { OpenSubagentAction, WithActions } from './affordances.tsx'
+import { ActionPlacementProvider, OpenSubagentAction, WithActions } from './affordances.tsx'
 import {
   AssistantRow,
   CompactionRow,
@@ -35,10 +35,18 @@ export interface TerminalTranscriptProps {
   className?: string
 }
 
-export function TerminalItemView({ item, fileUrl }: { item: TranscriptItem; fileUrl?: (path: string) => string }) {
+export function TerminalItemView({
+  item,
+  fileUrl,
+  attachmentUrl,
+}: {
+  item: TranscriptItem
+  fileUrl?: (path: string) => string
+  attachmentUrl?: (attachmentId: string) => string
+}) {
   switch (item.kind) {
     case 'user': {
-      return <UserRow item={item} />
+      return <UserRow item={item} attachmentUrl={attachmentUrl} />
     }
     case 'assistant_text': {
       return <AssistantRow item={item} />
@@ -122,12 +130,16 @@ export function TaskRow({
       {open ? (
         <div className="term-nested">
           {brief ? <BriefRow text={brief} terminal /> : null}
-          {block.children.map((leaf, index) => (
-            <Fragment key={leaf.key}>
-              {index > 0 && blockNeedsBlank(block.children[index - 1]!, leaf) ? <Blank /> : null}
-              {'run' in leaf ? <RunRow items={leaf.run} /> : <TerminalItemView item={leaf.item} fileUrl={fileUrl} />}
-            </Fragment>
-          ))}
+          {block.children.map((leaf, index) => {
+            const next = block.children[index + 1]
+            const view = 'run' in leaf ? <RunRow items={leaf.run} /> : <TerminalItemView item={leaf.item} fileUrl={fileUrl} />
+            return (
+              <Fragment key={leaf.key}>
+                {index > 0 && blockNeedsBlank(block.children[index - 1]!, leaf) ? <Blank /> : null}
+                {next && !blockNeedsBlank(leaf, next) ? <ActionPlacementProvider value="inline">{view}</ActionPlacementProvider> : view}
+              </Fragment>
+            )
+          })}
         </div>
       ) : null}
     </div>
@@ -177,18 +189,23 @@ export function TerminalTranscript({ state, fileUrl, fontSize, lineHeight, affor
       className={cn('term-transcript', className)}
     >
       <PeerNamesProvider items={state.items}>
-        {blocks.map((block, index) => (
-          <Fragment key={block.key}>
-            {index > 0 && blockNeedsBlank(blocks[index - 1]!, block) ? <Blank /> : null}
-            {'run' in block ? (
-              <RunRow items={block.run} />
-            ) : 'item' in block ? (
-              <TerminalItemView item={block.item} fileUrl={fileUrl} />
-            ) : (
-              <TaskRow block={block} fileUrl={fileUrl} />
-            )}
-          </Fragment>
-        ))}
+        {blocks.map((block, index) => {
+          const next = blocks[index + 1]
+          return (
+            <Fragment key={block.key}>
+              {index > 0 && blockNeedsBlank(blocks[index - 1]!, block) ? <Blank /> : null}
+              <ActionPlacementProvider value={next && !blockNeedsBlank(block, next) ? 'inline' : 'below'}>
+                {'run' in block ? (
+                  <RunRow items={block.run} />
+                ) : 'item' in block ? (
+                  <TerminalItemView item={block.item} fileUrl={fileUrl} />
+                ) : (
+                  <TaskRow block={block} fileUrl={fileUrl} />
+                )}
+              </ActionPlacementProvider>
+            </Fragment>
+          )
+        })}
         {working(state) ? (
           <>
             {state.items.length > 0 ? <Blank /> : null}

package/src/components/terminal/affordances.tsx

@@ -1,14 +1,15 @@
+import { Bot, BotOff, Check, Copy, Maximize2, SquareTerminal, Star, X, type LucideIcon } from 'lucide-react'
 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 = {
   hover?: boolean
   actions?: boolean
+  labels?: boolean
 }
 
-const DEFAULTS: Required<TerminalAffordances> = { hover: true, actions: true }
+const DEFAULTS: Required<TerminalAffordances> = { hover: true, actions: true, labels: false }
 
 const AffordanceContext = createContext<Required<TerminalAffordances>>(DEFAULTS)
 
@@ -18,7 +19,7 @@ export function useAffordances(): Required<TerminalAffordances> {
 
 export function resolveAffordances(value: TerminalAffordances | boolean | undefined): Required<TerminalAffordances> {
   if (value === false) {
-    return { hover: false, actions: false }
+    return { hover: false, actions: false, labels: false }
   }
   if (value === true || value === undefined) {
     return DEFAULTS
@@ -30,22 +31,79 @@ export function AffordanceProvider({ value, children }: { value: Required<Termin
   return <AffordanceContext.Provider value={value}>{children}</AffordanceContext.Provider>
 }
 
-export function WithActions({ actions, children, className }: { actions: ReactNode; children: ReactNode; className?: string }) {
+export type ActionPlacement = 'below' | 'inline'
+
+const PlacementContext = createContext<ActionPlacement>('below')
+
+export function ActionPlacementProvider({ value, children }: { value: ActionPlacement; children: ReactNode }) {
+  return <PlacementContext.Provider value={value}>{children}</PlacementContext.Provider>
+}
+
+export function WithActions({
+  actions,
+  children,
+  className,
+  placement,
+}: {
+  actions: ReactNode
+  children: ReactNode
+  className?: string
+  placement?: ActionPlacement
+}) {
   const { actions: enabled } = useAffordances()
+  const inherited = useContext(PlacementContext)
   if (!enabled) {
     return <>{children}</>
   }
   return (
-    <div className={cn('term-hoverable', className)}>
-      {children}
+    <div className={cn('term-hoverable', className)} data-placement={placement ?? inherited}>
+      <PlacementContext.Provider value="below">{children}</PlacementContext.Provider>
       <div className="term-actions">{actions}</div>
     </div>
   )
 }
 
+type Tone = 'magenta' | 'yellow' | 'red' | 'danger'
+
+function ActionButton({
+  icon: Icon,
+  word,
+  label,
+  tone,
+  pressed,
+  filled,
+  onPress,
+}: {
+  icon: LucideIcon
+  word: string
+  label: string
+  tone?: Tone
+  pressed?: boolean
+  filled?: boolean
+  onPress: () => void
+}) {
+  const { labels } = useAffordances()
+  return (
+    <button
+      type="button"
+      className="term-action"
+      title={label}
+      aria-label={label}
+      aria-pressed={pressed}
+      data-tone={tone}
+      onClick={(event) => {
+        event.stopPropagation()
+        onPress()
+      }}
+    >
+      <Icon aria-hidden className="term-action-icon" fill={filled ? 'currentColor' : 'none'} />
+      {labels ? <span className="term-action-word">{word}</span> : null}
+    </button>
+  )
+}
+
 // Bookmarks are a host concern (which items, where they persist); the transcript only needs
-// membership and a toggle. A missing provider renders no action at all, so embeddings that
-// never wire bookmarks pay nothing - the same contract AffordanceContext has.
+// membership and a toggle. A missing provider renders no action at all.
 export type BookmarkHandle = {
   has: (itemId: string) => boolean
   toggle: (itemId: string) => void
@@ -63,87 +121,52 @@ export function BookmarkAction({ id }: { id: string }) {
     return null
   }
   const active = handle.has(id)
-  const label = active ? 'Remove bookmark' : 'Bookmark'
   return (
-    <button
-      type="button"
-      className="term-action"
-      title={label}
-      aria-label={label}
-      aria-pressed={active}
-      onClick={(event) => {
-        event.stopPropagation()
-        handle.toggle(id)
-      }}
-    >
-      {active ? '★' : '☆'}
-    </button>
+    <ActionButton
+      icon={Star}
+      filled
+      word={active ? 'bookmarked' : 'bookmark'}
+      label={active ? 'Remove bookmark' : 'Bookmark'}
+      tone={active ? 'yellow' : undefined}
+      pressed={active}
+      onPress={() => handle.toggle(id)}
+    />
   )
 }
 
 export function OpenSubagentAction({ onOpen, label = 'Open sub-agent' }: { onOpen: () => void; label?: string }) {
-  return (
-    <button
-      type="button"
-      className="term-action"
-      title={label}
-      aria-label={label}
-      onClick={(event) => {
-        event.stopPropagation()
-        onOpen()
-      }}
-    >
-      ⤢
-    </button>
-  )
+  return <ActionButton icon={Maximize2} word="open" label={label} onPress={onOpen} />
 }
 
 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>
-  )
+  return <ActionButton icon={SquareTerminal} word="enter shell" label={label} tone="magenta" onPress={onOpen} />
 }
 
 export function KillShellAction({ onKill, label = 'Kill this shell' }: { onKill: () => void; label?: string }) {
+  return <ActionButton icon={X} word="kill" label={label} tone="danger" onPress={onKill} />
+}
+
+export function AgentWriteAction({ granted, label, onToggle }: { granted: boolean; label: string; onToggle: () => void }) {
   return (
-    <button
-      type="button"
-      className="term-action"
-      title={label}
-      aria-label={label}
-      data-tone="red"
-      onClick={(event) => {
-        event.stopPropagation()
-        onKill()
-      }}
-    >
-      {SHELL_KILL_GLYPH}
-    </button>
+    <ActionButton
+      icon={granted ? Bot : BotOff}
+      word={granted ? 'agent can type' : 'agent read-only'}
+      label={label}
+      tone={granted ? 'yellow' : undefined}
+      pressed={granted}
+      onPress={onToggle}
+    />
   )
 }
 
 export function CopyAction({ text, label = 'Copy' }: { text: string; label?: string }) {
   const [copied, setCopied] = useState(false)
   return (
-    <button
-      type="button"
-      className="term-action"
-      title={label}
-      aria-label={label}
-      onClick={(event) => {
-        event.stopPropagation()
+    <ActionButton
+      icon={copied ? Check : Copy}
+      word={copied ? 'copied' : 'copy'}
+      label={label}
+      onPress={() => {
         void copyText(text).then((ok) => {
           if (!ok) {
             return
@@ -152,8 +175,11 @@ export function CopyAction({ text, label = 'Copy' }: { text: string; label?: str
           setTimeout(() => setCopied(false), 1200)
         })
       }}
-    >
-      {copied ? '✓' : '⧉'}
-    </button>
+    />
   )
 }
+
+export function AgentWriteIcon({ granted, className }: { granted: boolean; className?: string }) {
+  const Icon = granted ? Bot : BotOff
+  return <Icon aria-hidden className={className} />
+}

package/src/components/terminal/height.ts

@@ -2,7 +2,7 @@ import type { FilePatch, PatchHunk } from '@workerdeck/protocol'
 import type { TranscriptItem } from '@workerdeck/react'
 import { compactionText, formatBytes, formatCost, formatDuration, toolInputPreview } from '../../lib/format.ts'
 import { taskChildItems, type TerminalBlock, type ToolCallItem } from './blocks.ts'
-import { IMAGE_BOX_LINES } from './image-box.ts'
+import { IMAGE_BOX_LINES, hostImagePathOf } from './image-box.ts'
 import { collapsedResult } from './result-preview.ts'
 import { shellBodyLines, shellFooterText, shellHeaderText } from './shell-row.ts'
 import { todoLine, todoPreview } from './todos.ts'
@@ -60,6 +60,10 @@ export function measureCh(surface: HTMLElement): number {
   return width
 }
 
+const MARKDOWN_IMAGE = /!\[[^\]]*\]\([^)]*\)/
+
+const MARKDOWN_IMAGE_LINE = /^\s*!\[[^\]]*\]\([^)\s]+\)\s*$/
+
 const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' })
 
 const WIDE_RANGES: [number, number][] = [
@@ -276,7 +280,8 @@ function stripInline(s: string): string {
 }
 
 type MdBlock =
-  | { t: 'p'; lines: string[] }
+  | { t: 'p'; lines: string[]; images: boolean }
+  | { t: 'image' }
   | { t: 'h'; text: string }
   | { t: 'fence'; code: string }
   | { t: 'list'; items: { lines: string[]; gutter: number; indent: number }[] }
@@ -302,11 +307,37 @@ function hardLines(source: string[]): string[] {
   return out
 }
 
+function isBlank(s: string | undefined): boolean {
+  return s !== undefined && s.trim() === ''
+}
+
+function listMarker(s: string): { depth: number; ordered: boolean; text: string } | undefined {
+  const m = /^(\s*)([-*+]|\d+\.)\s+(.*)$/.exec(s)
+  if (!m) {
+    return undefined
+  }
+  return { depth: Math.floor(m[1]!.length / 2), ordered: /\d/.test(m[2]!), text: m[3]! }
+}
+
+function numberHunk(hunk: PatchHunk): { number: number; text: string }[] {
+  let newLine = hunk.newStart
+  let oldLine = hunk.oldStart
+  return hunk.lines.map((line) => {
+    const kind = line.startsWith('+') ? 'add' : line.startsWith('-') ? 'remove' : 'context'
+    const text = line.slice(1)
+    const number = kind === 'add' ? newLine++ : kind === 'remove' ? oldLine++ : newLine
+    if (kind === 'context') {
+      oldLine++
+      newLine++
+    }
+    return { number, text }
+  })
+}
+
 function parseBlocks(md: string): MdBlock[] {
   const lines = md.split('\n')
   const blocks: MdBlock[] = []
   let i = 0
-  const isBlank = (s: string | undefined) => s !== undefined && s.trim() === ''
   while (i < lines.length) {
     const line = lines[i]!
     if (line.trim() === '') {
@@ -359,15 +390,6 @@ function parseBlocks(md: string): MdBlock[] {
       blocks.push({ t: 'quote', paras })
       continue
     }
-    const listMarker = (s: string) => {
-      const m = /^(\s*)([-*+]|\d+\.)\s+(.*)$/.exec(s)
-      if (!m) {
-        return undefined
-      }
-      const depth = Math.floor(m[1]!.length / 2)
-      const ordered = /\d/.test(m[2]!)
-      return { depth, ordered, text: m[3]! }
-    }
     if (listMarker(line)) {
       const items: { lines: string[]; gutter: number; indent: number }[] = []
       const gutters: number[] = []
@@ -431,7 +453,11 @@ function parseBlocks(md: string): MdBlock[] {
       para.push(lines[i]!)
       i += 1
     }
-    blocks.push({ t: 'p', lines: hardLines(para) })
+    if (para.length === 1 && MARKDOWN_IMAGE_LINE.test(para[0]!)) {
+      blocks.push({ t: 'image' })
+    } else {
+      blocks.push({ t: 'p', lines: hardLines(para), images: para.some((row) => MARKDOWN_IMAGE.test(row)) })
+    }
   }
   return blocks
 }
@@ -449,10 +475,14 @@ export function markdownHeight(md: string, m: CellMetrics, extraPx = 0): Acc {
       case 'p': {
         for (const line of block.lines) {
           const r = textLines(line, cols)
-          acc = add(acc, { px: r.lines * m.line, exact: r.exact })
+          acc = add(acc, { px: r.lines * m.line, exact: r.exact && !block.images })
         }
         break
       }
+      case 'image': {
+        acc = add(acc, { px: IMAGE_BOX_LINES * m.line, exact: true })
+        break
+      }
       case 'h': {
         const r = textLines(block.text, cols)
         acc = add(acc, { px: r.lines * m.line, exact: r.exact })
@@ -512,21 +542,7 @@ export function markdownHeight(md: string, m: CellMetrics, extraPx = 0): Acc {
 }
 
 function diffHeight(patch: FilePatch, m: CellMetrics, extraPx = 0): Acc {
-  const walk = (hunk: PatchHunk) => {
-    let newLine = hunk.newStart
-    let oldLine = hunk.oldStart
-    return hunk.lines.map((line) => {
-      const kind = line.startsWith('+') ? 'add' : line.startsWith('-') ? 'remove' : 'context'
-      const text = line.slice(1)
-      const number = kind === 'add' ? newLine++ : kind === 'remove' ? oldLine++ : newLine
-      if (kind === 'context') {
-        oldLine++
-        newLine++
-      }
-      return { number, text }
-    })
-  }
-  const hunks = patch.hunks.map(walk)
+  const hunks = patch.hunks.map(numberHunk)
   const numbered = patch.hunks.some((hunk) => hunk.newStart > 0)
   const width = numbered ? String(Math.max(...hunks.flat().map((row) => row.number), 1)).length : 0
   const columns = numbered ? width + 3 : 2
@@ -551,9 +567,9 @@ function toolRowHeight(item: ToolCallItem, m: CellMetrics, extraPx: number): Acc
   const backend = item.backend && item.backend !== 'server' ? ` · ${item.backend}` : ''
   let acc = rowH(`${item.name}(${preview})${backend}`, m, { gutterCells: 2, extraPx })
 
-  const images = item.result?.images
-  if (images?.length) {
-    acc = add(acc, { px: images.length * IMAGE_BOX_LINES * m.line, exact: true })
+  const boxes = (item.result?.images?.length ?? 0) + (hostImagePathOf(item) === undefined ? 0 : 1)
+  if (boxes > 0) {
+    acc = add(acc, { px: boxes * IMAGE_BOX_LINES * m.line, exact: true })
   }
 
   if (item.patch) {

package/src/components/terminal/image-box.ts

@@ -1,9 +1,40 @@
+import type { TranscriptItem } from '@workerdeck/react'
 import { formatBytes } from '../../lib/format.ts'
 
+type ToolCallItem = Extract<TranscriptItem, { kind: 'tool_call' }>
+
 export const IMAGE_BOX_LINES = 12
 
+const HOST_IMAGE_TOOLS = new Set(['CodexImageGeneration', 'CodexImageView'])
+
+const MEDIA_EXTENSIONS: Record<string, string> = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+  'image/svg+xml': 'svg',
+}
+
 export function imagePlaceholder(image: { bytes: number }): string {
   return `image · ${formatBytes(image.bytes)}`
 }
 
 export const IMAGE_UNAVAILABLE = 'image unavailable'
+
+export function hostImagePathOf(item: ToolCallItem): string | undefined {
+  if (!HOST_IMAGE_TOOLS.has(item.name)) {
+    return undefined
+  }
+  const input = item.input as { savedPath?: unknown; path?: unknown } | null
+  const path = input?.savedPath ?? input?.path
+  return typeof path === 'string' ? path : undefined
+}
+
+export function baseName(path: string): string {
+  return path.split(/[\\/]/).pop() || path
+}
+
+export function resultImageName(toolName: string, image: { partIndex: number; mediaType: string }): string {
+  const extension = MEDIA_EXTENSIONS[image.mediaType] ?? image.mediaType.split('/').pop() ?? 'img'
+  return `${toolName.toLowerCase()}-${image.partIndex + 1}.${extension}`
+}