@workerdeck/ui 2.8.0 → 2.10.0

package/src/components/prompt-area/dom-helpers.ts

@@ -139,6 +139,13 @@ export function getChipData(node: Node): unknown {
   return safeJsonParse(raw)
 }
 
+export function getChipSigil(node: Node): string | undefined {
+  if (!isChipElement(node)) {
+    return undefined
+  }
+  return node.dataset.chipSigil
+}
+
 /**
  * Length of a chip's plain-text representation (`trigger + displayText`).
  *
@@ -148,7 +155,7 @@ export function getChipData(node: Node): unknown {
  * `textContent` for resilience against externally-mutated nodes.
  */
 export function chipNodeTextLength(node: HTMLElement): number {
-  const trigger = node.dataset.chipTrigger ?? ''
+  const trigger = node.dataset.chipSigil ?? node.dataset.chipTrigger ?? ''
   const display = node.dataset.chipDisplay ?? node.textContent ?? ''
   return trigger.length + display.length
 }
@@ -174,6 +181,7 @@ export function chipNodeToSegment(node: Node): ChipSegment | null {
     return null
   }
 
+  const sigil = getChipSigil(node)
   const data = getChipData(node)
   const autoResolved = getChipAutoResolved(node)
 
@@ -182,6 +190,7 @@ export function chipNodeToSegment(node: Node): ChipSegment | null {
     trigger,
     value,
     displayText,
+    ...(sigil !== undefined ? { sigil } : {}),
     ...(data !== undefined ? { data } : {}),
     ...(autoResolved ? { autoResolved: true } : {}),
   }

package/src/components/prompt-area/index.ts

@@ -7,4 +7,13 @@ export { PromptArea } from './prompt-area.tsx'
 export { usePromptAreaState } from './use-prompt-area-state.ts'
 export { commandTrigger, mentionTrigger, hashtagTrigger, launchTrigger } from './trigger-presets.ts'
 export { segmentsToPlainText, plainTextToSegments, isSegmentsEmpty, getChipsByTrigger } from './segment-helpers.ts'
-export type { PromptAreaHandle, PromptAreaProps, Segment, ChipSegment, TextSegment, TriggerConfig, TriggerSuggestion } from './types.ts'
+export type {
+  ChipOptions,
+  PromptAreaHandle,
+  PromptAreaProps,
+  Segment,
+  ChipSegment,
+  TextSegment,
+  TriggerConfig,
+  TriggerSuggestion,
+} from './types.ts'

package/src/components/prompt-area/prompt-area-engine.ts

@@ -6,9 +6,16 @@ import type { Segment, ChipSegment, TriggerConfig, TriggerPosition, ActiveTrigge
 
 // Serialization
 
+/**
+ * A chip's plain-text form: `{sigil ?? trigger}{displayText}` (e.g., "@Alice").
+ */
+export function chipPlainText(seg: ChipSegment): string {
+  return `${seg.sigil ?? seg.trigger}${seg.displayText}`
+}
+
 /**
  * Converts an array of segments to a plain text string.
- * Chips are represented as `{trigger}{displayText}` (e.g., "@Alice").
+ * Chips are represented by {@link chipPlainText}.
  */
 export function segmentsToPlainText(segments: Segment[]): string {
   return segments
@@ -16,7 +23,7 @@ export function segmentsToPlainText(segments: Segment[]): string {
       if (seg.type === 'text') {
         return seg.text
       }
-      return `${seg.trigger}${seg.displayText}`
+      return chipPlainText(seg)
     })
     .join('')
 }
@@ -45,7 +52,7 @@ export function truncateSegmentsToLength(segments: Segment[], maxLength: number)
   const result: Segment[] = []
   let length = 0
   for (const seg of segments) {
-    const segLength = seg.type === 'text' ? seg.text.length : seg.trigger.length + seg.displayText.length
+    const segLength = seg.type === 'text' ? seg.text.length : chipPlainText(seg).length
     if (length + segLength <= maxLength) {
       result.push(seg)
       length += segLength
@@ -195,7 +202,8 @@ export function detectActiveTrigger(text: string, cursorPos: number, triggers: T
 export function resolveChip(
   segments: Segment[],
   activeTrigger: ActiveTrigger,
-  chip: { value: string; displayText: string; data?: unknown; autoResolved?: boolean },
+  chip: { value: string; displayText: string; sigil?: string; data?: unknown; autoResolved?: boolean },
+  trailingText = ' ',
 ): { segments: Segment[]; cursorOffset: number } {
   const triggerStart = activeTrigger.startOffset
   const triggerEnd = triggerStart + 1 + activeTrigger.query.length // +1 for trigger char
@@ -205,7 +213,7 @@ export function resolveChip(
 
   for (const seg of segments) {
     if (seg.type === 'chip') {
-      const chipText = `${seg.trigger}${seg.displayText}`
+      const chipText = chipPlainText(seg)
       const chipStart = offset
       const chipEnd = offset + chipText.length
 
@@ -239,16 +247,17 @@ export function resolveChip(
           trigger: activeTrigger.config.char,
           value: chip.value,
           displayText: chip.displayText,
+          ...(chip.sigil !== undefined ? { sigil: chip.sigil } : {}),
           ...(chip.data !== undefined ? { data: chip.data } : {}),
           ...(chip.autoResolved ? { autoResolved: true } : {}),
         }
         newSegments.push(newChip)
 
-        // Add trailing space after chip, then any remaining text
+        // Add the trailing text (a space by default) after the chip, then any remaining text
         if (afterText) {
-          newSegments.push({ type: 'text', text: ' ' + afterText.replace(/^\s/, '') })
+          newSegments.push({ type: 'text', text: trailingText + afterText.replace(/^\s/, '') })
         } else {
-          newSegments.push({ type: 'text', text: ' ' })
+          newSegments.push({ type: 'text', text: trailingText })
         }
       }
 
@@ -266,14 +275,14 @@ export function resolveChip(
     if (seg.type === 'text') {
       runningOffset += seg.text.length
     } else {
-      runningOffset += seg.trigger.length + seg.displayText.length
+      runningOffset += chipPlainText(seg).length
       if (seg.value === chip.value && seg.displayText === chip.displayText && seg.trigger === activeTrigger.config.char) {
         lastChipEndOffset = runningOffset
       }
     }
   }
-  // +1 accounts for the trailing space after the chip
-  const cursorOffset = lastChipEndOffset === -1 ? runningOffset : lastChipEndOffset + 1
+  // The caret lands after the chip and its trailing text
+  const cursorOffset = lastChipEndOffset === -1 ? runningOffset : lastChipEndOffset + trailingText.length
 
   return { segments: merged, cursorOffset }
 }
@@ -302,7 +311,7 @@ export function resolveText(
 
   for (const seg of segments) {
     if (seg.type === 'chip') {
-      const chipEnd = offset + `${seg.trigger}${seg.displayText}`.length
+      const chipEnd = offset + chipPlainText(seg).length
       // A trigger range can never overlap a chip - chips are atomic - so a chip
       // is either wholly before or wholly after, and is kept either way.
       if (chipEnd <= triggerStart || offset >= triggerEnd) {
@@ -377,7 +386,7 @@ export function revertChipAtIndex(segments: Segment[], index: number): { segment
     return null
   }
 
-  const revertedText = `${seg.trigger}${seg.displayText}`
+  const revertedText = chipPlainText(seg)
   const result = [...segments.slice(0, index), { type: 'text' as const, text: revertedText }, ...segments.slice(index + 1)]
   return { segments: mergeAdjacentTextSegments(result), revertedText }
 }
@@ -491,7 +500,7 @@ export function replaceTextRange(segments: Segment[], start: number, end: number
 
   for (const seg of segments) {
     if (seg.type === 'chip') {
-      const chipText = `${seg.trigger}${seg.displayText}`
+      const chipText = chipPlainText(seg)
       const chipStart = offset
       const chipEnd = offset + chipText.length
 

package/src/components/prompt-area/types.ts

@@ -23,6 +23,12 @@ export type ChipSegment = {
   value: string
   /** The display text shown in the chip */
   displayText: string
+  /**
+   * The character the chip serialises and renders with, when it differs from
+   * `trigger`. The trigger is the menu the chip came from; the sigil is the
+   * token the host parses. Unset, the trigger character is the sigil.
+   */
+  sigil?: string
   /** Optional data payload attached to the chip */
   data?: unknown
   /**
@@ -74,6 +80,11 @@ export type TriggerSuggestion = {
   data?: unknown
 }
 
+export type ChipOptions = {
+  sigil?: string
+  trailingText?: string
+}
+
 /**
  * Configuration for a trigger character.
  */
@@ -113,6 +124,15 @@ export type TriggerConfig = {
    * `onChipAdd` does not fire either.
    */
   insertAsText?: (suggestion: TriggerSuggestion) => string | undefined
+  /**
+   * For 'dropdown' mode: per-suggestion overrides for the chip a selection
+   * resolves to. `sigil` replaces the trigger character in the chip's text and
+   * serialisation (a `/` menu inserting a `$name` token); `trailingText` is
+   * the editable text placed after the chip in place of the default single
+   * space (it is inserted verbatim, so include the leading space). Return
+   * undefined for the plain chip.
+   */
+  chipOptions?: (suggestion: TriggerSuggestion) => ChipOptions | undefined
   /**
    * For 'callback' and 'launch' modes: called when the trigger is activated.
    * Receives the full input text and cursor position. For 'launch' it fires on

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

@@ -10,6 +10,7 @@ import {
   revertChipAtIndex,
   replaceTextRange,
   toggleMarkdownWrap,
+  chipPlainText,
 } from './prompt-area-engine.ts'
 import {
   getListContext,
@@ -138,7 +139,7 @@ export function usePromptAreaKeydown({
         if (s.type === 'text') {
           targetOffset += s.text.length
         } else {
-          targetOffset += s.trigger.length + s.displayText.length
+          targetOffset += chipPlainText(s).length
         }
       }
       targetOffset += result.revertedText.length

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

@@ -12,6 +12,7 @@ import {
   resolveChip,
   resolveText,
   truncateSegmentsToLength,
+  chipPlainText,
 } from './prompt-area-engine.ts'
 import {
   autoFormatListPrefix,
@@ -223,6 +224,9 @@ export function usePromptArea({
           chip.dataset.chipTrigger = seg.trigger
           chip.dataset.chipValue = seg.value
           chip.dataset.chipDisplay = seg.displayText
+          if (seg.sigil !== undefined) {
+            chip.dataset.chipSigil = seg.sigil
+          }
           if (seg.data !== undefined) {
             const json = safeJsonStringify(seg.data)
             if (json) {
@@ -236,7 +240,7 @@ export function usePromptArea({
           const chipStyle = triggerConfig?.chipStyle ?? 'pill'
           chip.dataset.chipStyle = chipStyle
           chip.className = cn('prompt-area-chip', chipStyle === 'inline' && 'prompt-area-chip--inline', triggerConfig?.chipClassName)
-          chip.textContent = `${seg.trigger}${seg.displayText}`
+          chip.textContent = chipPlainText(seg)
           chip.setAttribute('role', 'button')
           chip.setAttribute('tabindex', '-1')
           editor.appendChild(chip)
@@ -598,10 +602,12 @@ export function usePromptArea({
       }
 
       const displayText = activeTrigger.config.onSelect?.(suggestion) ?? suggestion.label
+      const options = activeTrigger.config.chipOptions?.(suggestion)
 
       const chipData = {
         value: suggestion.value,
         displayText: displayText || suggestion.label,
+        ...(options?.sigil !== undefined ? { sigil: options.sigil } : {}),
         data: suggestion.data,
       }
 
@@ -616,7 +622,7 @@ export function usePromptArea({
         }, 0)
         return
       }
-      const result = resolveChip(segments, activeTrigger, chipData)
+      const result = resolveChip(segments, activeTrigger, chipData, options?.trailingText)
 
       onChange(result.segments)
       renderSegmentsToDOM(result.segments)

package/src/components/terminal/StatusLine.tsx

@@ -75,10 +75,11 @@ export function TerminalStatusLine({
     )
   }
 
-  if (state.totalCostUsd > 0) {
+  const costUsd = state.costUsd ?? (state.totalCostUsd || undefined)
+  if (costUsd !== undefined && costUsd > 0) {
     parts.push(
       <Ink key="cost" tone="faint">
-        {formatCost(state.totalCostUsd)}
+        {formatCost(costUsd)}
       </Ink>,
     )
   }

package/src/components/terminal/file-link.tsx

@@ -0,0 +1,20 @@
+import { createContext, useContext, type ReactNode } from 'react'
+
+export type FileLinkOpener = (path: string, line?: number) => void
+
+export type FileLinkHandle = {
+  cwd?: string
+  open: FileLinkOpener
+}
+
+const FileLinkContext = createContext<FileLinkHandle | undefined>(undefined)
+
+// A missing provider leaves every link an ordinary anchor, so embeddings that have nowhere to
+// open a file pay nothing - the same contract BookmarkContext has.
+export function FileLinkProvider({ value, children }: { value: FileLinkHandle | undefined; children: ReactNode }) {
+  return <FileLinkContext.Provider value={value}>{children}</FileLinkContext.Provider>
+}
+
+export function useFileLinks(): FileLinkHandle | undefined {
+  return useContext(FileLinkContext)
+}

package/src/components/terminal/items.tsx

@@ -3,6 +3,7 @@ import type { TranscriptItem } from '@workerdeck/react'
 import { compactionText, formatBytes, formatCost, formatDuration, toolInputPreview } from '../../lib/format.ts'
 import { isMutatingTool } from '../../lib/tool-icon.ts'
 import { usePulse } from '../agent/pulse.tsx'
+import { PromptTokenText } from '../agent/PromptTokenText.tsx'
 import { BookmarkAction, CopyAction, WithActions } from './affordances.tsx'
 import { TerminalDiff } from './diff.tsx'
 import { TerminalMarkdown } from './markdown.tsx'
@@ -46,7 +47,7 @@ export function UserRow({ item }: { item: Extract<TranscriptItem, { kind: 'user'
         {item.text
           ? item.text.split('\n').map((line, index) => (
               <Row key={index} glyph={index === 0 ? PROMPT_GLYPH : undefined} glyphTone="dim" tone="fg">
-                {line || ' '}
+                {line ? <PromptTokenText text={line} /> : ' '}
               </Row>
             ))
           : null}
@@ -270,7 +271,7 @@ export function TurnResultRow({ item }: { item: Extract<TranscriptItem, { kind:
   return (
     <div>
       <Row tone={item.isError ? 'red' : 'faint'}>
-        {item.isError ? item.subtype : 'done'} · {formatDuration(item.durationMs)} · {formatCost(item.totalCostUsd)}
+        {item.isError ? item.subtype : 'done'} · {formatDuration(item.durationMs)} · {formatCost(item.costUsd ?? item.totalCostUsd)}
       </Row>
       {item.errors?.map((message, index) => (
         <Row key={index} tone="red">

package/src/components/terminal/markdown.tsx

@@ -1,7 +1,9 @@
 import { memo, type ReactNode } from 'react'
 import { Streamdown, type Components } from 'streamdown'
 import { cn } from '../../lib/utils.ts'
+import { parseFileLink } from '../../lib/file-link.ts'
 import { CopyAction, WithActions } from './affordances.tsx'
+import { useFileLinks } from './file-link.tsx'
 import { Band } from './row.tsx'
 
 function codeText(node: ReactNode): string {
@@ -45,6 +47,34 @@ function heading(tone: 'bright' | 'fg'): Components['h1'] {
   }
 }
 
+// An agent writes a file as a markdown link far more often than it writes a URL, and the link text is
+// its name, not its path: an anchor to a scheme-less href resolves against the host page and leads nowhere.
+function Link({ href, children }: { href?: string; children: ReactNode }) {
+  const links = useFileLinks()
+  const file = links ? parseFileLink(href, links.cwd) : undefined
+  if (file) {
+    return (
+      <button
+        type="button"
+        className="term-link"
+        data-tone="blue"
+        title={file.line === undefined ? file.path : `${file.path}:${file.line}`}
+        onClick={(event) => {
+          event.stopPropagation()
+          links?.open(file.path, file.line)
+        }}
+      >
+        {children}
+      </button>
+    )
+  }
+  return (
+    <a className="term-link" data-tone="blue" href={href} target="_blank" rel="noreferrer">
+      {children}
+    </a>
+  )
+}
+
 const TERMINAL_COMPONENTS: Components = {
   p: ({ children }) => <div className="term-block">{children}</div>,
 
@@ -85,11 +115,7 @@ const TERMINAL_COMPONENTS: Components = {
     </strong>
   ),
   em: ({ children }) => <em className="term-em">{children}</em>,
-  a: ({ children, href }) => (
-    <a className="term-link" data-tone="blue" href={href} target="_blank" rel="noreferrer">
-      {children}
-    </a>
-  ),
+  a: ({ children, href }) => <Link href={href}>{children}</Link>,
 
   table: ({ children }) => (
     <div className="term-block term-table-wrap">

package/src/index.ts

@@ -61,6 +61,10 @@ export { TerminalDiff, previewPatch } from './components/terminal/diff.tsx'
 export { TerminalMarkdown, type TerminalMarkdownProps } from './components/terminal/markdown.tsx'
 export { Band, Blank, Ink, Row, type RowProps, type Tone } from './components/terminal/row.tsx'
 export { CopyAction, WithActions, useAffordances, type TerminalAffordances } from './components/terminal/affordances.tsx'
+export { FileLinkProvider, useFileLinks, type FileLinkHandle, type FileLinkOpener } from './components/terminal/file-link.tsx'
+export { parseFileLink, type FileLink } from './lib/file-link.ts'
+export { matchPath, type PathHit, type PathMatch } from './lib/path-match.ts'
+export { usePathLinks, resolveAgainstCwd } from './components/agent/use-path-links.ts'
 export { Conversation, ConversationContent, ConversationScrollButton, type ConversationProps } from './components/agent/Conversation.tsx'
 export { Message, MessageContent, type MessageProps } from './components/agent/Message.tsx'
 export {
@@ -86,7 +90,15 @@ export {
   type QuestionPromptProps,
   type QuestionBehaviorMeta,
 } from './components/agent/QuestionPrompt.tsx'
-export { Composer, skillPrompt, type ComposerFileMatch, type ComposerHandle, type ComposerProps } from './components/agent/Composer.tsx'
+export { Composer, type ComposerFileMatch, type ComposerHandle, type ComposerProps } from './components/agent/Composer.tsx'
+export {
+  mergeComposerRows,
+  rankComposerRows,
+  matchClientCommand,
+  skillPrompt,
+  type ClientCommand,
+  type ComposerRow,
+} from './components/agent/composer-commands.ts'
 export { ModelSelect, type ModelSelectProps } from './components/agent/ModelSelect.tsx'
 export {
   PERMISSION_MODES,
@@ -109,7 +121,7 @@ export { SkillsDialog, type SkillsDialogProps } from './components/agent/SkillsD
 export { HostFilesDialog, type HostFilesDialogProps } from './components/agent/HostFilesDialog.tsx'
 export { SessionList, SessionListItem, type SessionListItemProps, type SessionListProps } from './components/agent/SessionList.tsx'
 export { SessionBrowser, rowShapeClass, type SessionBrowserProps } from './components/agent/SessionBrowser.tsx'
-export { SessionItem, type SessionItemProps } from './components/agent/SessionItem.tsx'
+export { SessionItem, type SelectModifiers, type SessionItemProps } from './components/agent/SessionItem.tsx'
 export { SessionStatusIcon } from './components/agent/SessionStatusIcon.tsx'
 export { EngineIcon, engineMark, vendorMarkClass, vendorTextClass } from './components/agent/EngineIcon.tsx'
 export { type Step, StepRow, StepToggle, runningSteps, sessionSteps } from './components/agent/SessionSteps.tsx'

package/src/lib/file-link.ts

@@ -0,0 +1,70 @@
+export type FileLink = {
+  path: string
+  line?: number
+}
+
+const SCHEME = /^[a-zA-Z][a-zA-Z0-9+.-]*:/
+const TRAILING_LINE = /^(.*?):(\d+)(?::\d+)?$/
+const FRAGMENT_LINE = /^L(\d+)/
+
+// What an agent writes as a markdown link target when it means a file on the host: `./SPEC.md`,
+// `docs/AUTH.md#anchor`, `/Users/me/project/src/main.ts:42`, `file:///tmp/out.txt`. Anything with a
+// real scheme, and anything relative that arrives before the session's cwd is known, stays a web link.
+export function parseFileLink(href: string | undefined, cwd: string | undefined): FileLink | undefined {
+  const raw = href?.trim()
+  if (!raw || raw.startsWith('#') || raw.startsWith('//')) {
+    return undefined
+  }
+
+  let target = raw
+  if (SCHEME.test(target)) {
+    if (!target.startsWith('file:')) {
+      return undefined
+    }
+    try {
+      target = decodeURIComponent(new URL(target).pathname)
+    } catch {
+      return undefined
+    }
+  }
+
+  let line: number | undefined
+  const hash = target.indexOf('#')
+  if (hash !== -1) {
+    line = readLine(FRAGMENT_LINE.exec(target.slice(hash + 1))?.[1])
+    target = target.slice(0, hash)
+  }
+
+  const suffix = TRAILING_LINE.exec(target)
+  if (suffix) {
+    target = suffix[1]!
+    line ??= readLine(suffix[2])
+  }
+
+  if (!target) {
+    return undefined
+  }
+
+  const path = target.startsWith('/') ? normalize(target) : cwd ? normalize(`${cwd}/${target}`) : undefined
+  return path ? { path, ...(line === undefined ? {} : { line }) } : undefined
+}
+
+function readLine(value: string | undefined): number | undefined {
+  const parsed = value === undefined ? Number.NaN : Number(value)
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined
+}
+
+function normalize(path: string): string {
+  const out: string[] = []
+  for (const part of path.split('/')) {
+    if (part === '' || part === '.') {
+      continue
+    }
+    if (part === '..') {
+      out.pop()
+      continue
+    }
+    out.push(part)
+  }
+  return `/${out.join('/')}`
+}

package/src/lib/path-match.ts

@@ -0,0 +1,51 @@
+// One path segment: no whitespace, no separator, none of the characters that bracket a path in
+// prose. `:` is out because it introduces `:line`.
+const SEG = '[^\\s:\'"`()\\[\\]{}<>|]+'
+
+// The first segment of a relative path additionally cannot start with `@`: in an `@file` mention
+// (`@_docs/BACKLOG.md`) the `@` is the mention's sigil, not part of the name.
+const HEAD = '[^\\s:\'"`()\\[\\]{}<>|@,]+'
+
+// The match must start at a token boundary, never consumed into the path: unanchored,
+// `@_docs/BACKLOG.md` matched the suffix `/BACKLOG.md` and opened at the filesystem root.
+const PATH_PATTERN = new RegExp(`(?:^|[\\s'"\`([{<@,])((?:\\.\\.?)?(?:/${SEG})+|${HEAD}(?:/${SEG})+)(?::(\\d+))?`)
+
+const FILE_PATTERN = /^([\w.@-]+\.[A-Za-z0-9]{1,10})(?::(\d+))?$/
+
+const TRAILING = /[.,;:!?)\]}'"`]+$/
+
+const FILENAME = /\.[A-Za-z0-9]{1,10}$/
+
+export type PathHit = { path: string; line?: number }
+
+export type PathMatch = PathHit & {
+  // How much of the inspected text the path accounted for, the "mostly a path" test the hover makes.
+  length: number
+}
+
+export function matchPath(text: string | null | undefined, inCode = false): PathMatch | undefined {
+  const source = text ?? ''
+  const match = PATH_PATTERN.exec(source)
+  if (!match) {
+    return inCode ? matchFilename(source) : undefined
+  }
+  const path = match[1]!.replace(TRAILING, '')
+  if (!path.includes('/') || path.endsWith('/')) {
+    return undefined
+  }
+  const rooted = path.startsWith('/') || path.startsWith('./') || path.startsWith('../')
+  if (!rooted && !FILENAME.test(path)) {
+    return undefined
+  }
+  const line = match[2] ? Number(match[2]) : undefined
+  return { path, line, length: path.length + (match[2] ? match[2].length + 1 : 0) }
+}
+
+function matchFilename(text: string): PathMatch | undefined {
+  const hit = FILE_PATTERN.exec(text.trim())
+  if (!hit) {
+    return undefined
+  }
+  const line = hit[2] ? Number(hit[2]) : undefined
+  return { path: hit[1]!, line, length: hit[0].length }
+}

package/src/lib/session-cost.ts

@@ -0,0 +1,65 @@
+import {
+  type ByModel,
+  type CostBreakdown,
+  type TokenUsage,
+  UNPRICED_WARN_SHARE,
+  canonicalModel,
+  costOf,
+  costOfByModel,
+  rateFor,
+  totalTokens,
+} from '@workerdeck/protocol'
+
+export type SessionCostRow = {
+  model: string
+  usage: TokenUsage
+  tokens: number
+  costUsd: number | undefined
+}
+
+export type SessionCost = {
+  displayUsd: number | undefined
+  computedUsd: number | undefined
+  reportedUsd: number | undefined
+  breakdown: CostBreakdown
+  rows: SessionCostRow[]
+  unpricedShare: number
+  showUnpricedWarning: boolean
+  // Both figures price the same tokens, one by the engine and one by us, so a gap is the thing worth reading.
+  gapUsd: number | undefined
+}
+
+export type SessionCostInput = {
+  costUsd?: number
+  totalCostUsd?: number
+  usageByModel?: ByModel
+}
+
+const GAP_SHARE = 0.02
+
+export function sessionCost(input: SessionCostInput): SessionCost {
+  const byModel = input.usageByModel ?? {}
+  const breakdown = costOfByModel(byModel)
+  const computedUsd = input.costUsd ?? (breakdown.unpriced || Object.keys(byModel).length === 0 ? undefined : breakdown.total)
+  const reportedUsd = input.totalCostUsd
+  const rows = Object.entries(byModel)
+    .map(([model, usage]) => ({
+      model: canonicalModel(model),
+      usage,
+      tokens: totalTokens(usage),
+      costUsd: rateFor(model) ? costOf(usage, model).total : undefined,
+    }))
+    .sort((a, b) => b.tokens - a.tokens)
+  const gap = computedUsd !== undefined && reportedUsd !== undefined ? reportedUsd - computedUsd : undefined
+  const worthShowing = gap !== undefined && Math.abs(gap) > Math.max(0.01, GAP_SHARE * Math.max(computedUsd ?? 0, reportedUsd ?? 0))
+  return {
+    displayUsd: computedUsd ?? reportedUsd,
+    computedUsd,
+    reportedUsd,
+    breakdown,
+    rows,
+    unpricedShare: breakdown.unpricedShare,
+    showUnpricedWarning: breakdown.unpricedShare > UNPRICED_WARN_SHARE,
+    gapUsd: worthShowing ? gap : undefined,
+  }
+}

package/src/styles/terminal.css

@@ -416,6 +416,21 @@
   text-underline-offset: 2px;
 }
 
+/* A link to a file opens through the host rather than the address bar, so it is a button.
+ * Outside `[data-terminal]` too: a cards transcript renders the same markdown. */
+button.term-link {
+  appearance: none;
+  background: none;
+  border: 0;
+  padding: 0;
+  font: inherit;
+  color: inherit;
+  cursor: pointer;
+  text-align: inherit;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
 /* A file path, while the modifier that would open it is held.
  *
  * Only then, and that is the point: a path *is* clickable but only under