@workerdeck/ui 2.8.0 → 2.9.0

package/src/components/agent/UsageMeters.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useState } from 'react'
-import type { UsageWindowRow } from '@workerdeck/protocol'
+import { usageIsStale, type UsageWindowRow } from '@workerdeck/protocol'
 import { RotateCcw } from 'lucide-react'
 import { cn } from '../../lib/utils.ts'
 import { formatAgoPrecise, formatCountdown, formatRateLimitWindowLong, rateLimitWindowSeconds } from '../../lib/format.ts'
@@ -33,6 +33,9 @@ export function UsageMeters({ windows, now, className }: { windows: UsageWindowR
 function UsageMeter({ window, now }: { window: UsageWindowRow; now: number }) {
   const { key: windowKey, info, updatedAt, inferredReset } = window
   const utilization = info.utilization ?? 0
+  // Drawn differently rather than hidden: this is still the best answer anyone has, it is just not a claim about
+  // right now, and a stale reading asserted as current is how a number from two days ago passes for the truth.
+  const stale = usageIsStale(window, now)
   const resetsAtMs = info.resetsAt !== undefined ? info.resetsAt * 1000 : undefined
   const duration = rateLimitWindowSeconds(windowKey)
   const remaining = resetsAtMs !== undefined ? (resetsAtMs - now) / 1000 : undefined
@@ -44,13 +47,18 @@ function UsageMeter({ window, now }: { window: UsageWindowRow; now: number }) {
     <div>
       <div className="flex items-baseline justify-between gap-3">
         <span className="truncate text-body-sm text-fg-1">{formatRateLimitWindowLong(windowKey)}</span>
-        <span className={cn('shrink-0 font-mono text-body-sm font-medium', info.status === 'rejected' ? 'text-danger' : 'text-fg-1')}>
+        <span
+          className={cn(
+            'shrink-0 font-mono text-body-sm font-medium',
+            info.status === 'rejected' ? 'text-danger' : stale ? 'text-fg-4' : 'text-fg-1',
+          )}
+        >
           {utilization.toFixed(0)}% used
         </span>
       </div>
       <div className="relative mt-2 h-2 rounded-full bg-border">
         <div
-          className={cn('h-full rounded-full', meterTintClass(utilization))}
+          className={cn('h-full rounded-full', meterTintClass(utilization), stale && 'opacity-40')}
           style={{ width: `${Math.min(100, Math.max(2, utilization))}%` }}
         />
         {pace !== undefined ? (
@@ -71,7 +79,12 @@ function UsageMeter({ window, now }: { window: UsageWindowRow; now: number }) {
         {info.isUsingOverage ? <span className="text-warning">overage</span> : null}
         {info.status === 'rejected' ? <span className="text-danger">limit reached</span> : null}
         {inferredReset ? <span>window reset · nothing reported since</span> : null}
-        {updatedAt && !inferredReset ? <span>{formatAgoPrecise(updatedAt, now)}</span> : null}
+        {updatedAt && !inferredReset ? (
+          <span className={cn(stale && 'text-warning')}>
+            {stale ? 'last reported ' : ''}
+            {formatAgoPrecise(updatedAt, now)}
+          </span>
+        ) : null}
       </div>
     </div>
   )

package/src/components/agent/composer-commands.ts

@@ -0,0 +1,142 @@
+import type { SkillInfo, SlashCommandInfo } from '@workerdeck/protocol'
+
+export type ClientCommand = {
+  name: string
+  description: string
+  argumentHint?: string
+  // Selecting the row populates the composer with `/name ` instead of resolving to a chip, so the
+  // argument is typed before anything is submitted.
+  requiresArgs?: boolean
+  // True when the command consumed the input. False hands the text back to the engine, which is how
+  // `/model` with no argument still reaches a CLI that implements it natively.
+  run: (args: string) => boolean
+}
+
+export type ComposerRow =
+  | { kind: 'command'; name: string; description?: string; argumentHint?: string; aliases?: string[] }
+  | { kind: 'client'; name: string; description?: string; argumentHint?: string; command: ClientCommand }
+  | { kind: 'skill'; name: string; label: string; description?: string; enabled: boolean; scope?: string; skill: SkillInfo }
+
+const KIND_ORDER: Record<ComposerRow['kind'], number> = { command: 0, client: 1, skill: 2 }
+
+export function cleanCommandName(name: string): string {
+  return name.replace(/\s*\(MCP\)$/i, '')
+}
+
+export function skillPrompt(skill: SkillInfo): string {
+  const base = skill.defaultPrompt?.trim() || `Use the ${skill.displayName ?? skill.name} skill:`
+  return /\s$/.test(base) ? base : base + ' '
+}
+
+export function mergeComposerRows(sources: {
+  commands?: readonly SlashCommandInfo[]
+  clientCommands?: readonly ClientCommand[]
+  skills?: readonly SkillInfo[]
+}): ComposerRow[] {
+  const rows: ComposerRow[] = []
+  const engineNames = new Set<string>()
+  for (const command of sources.commands ?? []) {
+    const name = cleanCommandName(command.name)
+    if (engineNames.has(name)) {
+      continue
+    }
+    engineNames.add(name)
+    for (const alias of command.aliases ?? []) {
+      engineNames.add(cleanCommandName(alias))
+    }
+    rows.push({ kind: 'command', name, description: command.description, argumentHint: command.argumentHint, aliases: command.aliases })
+  }
+  for (const command of sources.clientCommands ?? []) {
+    if (engineNames.has(command.name)) {
+      continue
+    }
+    rows.push({ kind: 'client', name: command.name, description: command.description, argumentHint: command.argumentHint, command })
+  }
+  for (const skill of sources.skills ?? []) {
+    rows.push({
+      kind: 'skill',
+      name: skill.name,
+      label: skill.displayName ?? skill.name,
+      description: skill.shortDescription ?? skill.description,
+      enabled: skill.enabled,
+      scope: skill.scope,
+      skill,
+    })
+  }
+  return rows
+}
+
+function haystacks(row: ComposerRow): string[] {
+  if (row.kind === 'skill') {
+    return [row.name, row.label, ...row.name.split(/[-:_]/)]
+  }
+  return [row.name, ...(row.kind === 'command' ? (row.aliases ?? []) : []), ...row.name.split(':')]
+}
+
+export function matchScore(query: string, candidates: readonly string[]): number {
+  const needle = query.toLowerCase()
+  const lowered = candidates.map((s) => s.toLowerCase())
+  if (lowered.some((h) => h.startsWith(needle))) {
+    return 2
+  }
+  return lowered.some((h) => h.includes(needle)) ? 1 : 0
+}
+
+export function rankComposerRows(query: string, rows: readonly ComposerRow[]): ComposerRow[] {
+  const scored: Array<{ score: number; index: number; row: ComposerRow }> = []
+  rows.forEach((row, index) => {
+    if (row.kind === 'skill' && !row.enabled) {
+      return
+    }
+    const score = matchScore(query, haystacks(row))
+    if (score > 0) {
+      scored.push({ score, index, row })
+    }
+  })
+  scored.sort((a, b) => b.score - a.score || KIND_ORDER[a.row.kind] - KIND_ORDER[b.row.kind] || a.index - b.index)
+  return scored.map(({ row }) => row)
+}
+
+export function matchClientCommand(text: string, commands: readonly ClientCommand[]): { command: ClientCommand; args: string } | undefined {
+  const match = /^\/([\w:-]+)[ \t]*([\s\S]*)$/.exec(text.trim())
+  if (!match) {
+    return undefined
+  }
+  const command = commands.find((c) => c.name === match[1])
+  return command ? { command, args: match[2]!.trim() } : undefined
+}
+
+// The serializable projection a native host (the VS Code QuickPick) renders. `insertText` is resolved here
+// so no second surface reimplements skillPrompt or the leading slash.
+export type ComposerCommandRow = {
+  kind: ComposerRow['kind']
+  name: string
+  label: string
+  description?: string
+  scope?: string
+  enabled: boolean
+  insertText: string
+}
+
+export function composerCommandRows(rows: readonly ComposerRow[]): ComposerCommandRow[] {
+  return rows.map((row) =>
+    row.kind === 'skill'
+      ? {
+          kind: row.kind,
+          name: row.name,
+          label: row.label,
+          description: row.description,
+          scope: row.scope,
+          enabled: row.enabled,
+          insertText: skillPrompt(row.skill),
+        }
+      : {
+          kind: row.kind,
+          name: row.name,
+          label: `/${row.name}`,
+          description: row.description,
+          enabled: true,
+          insertText: `/${row.name} `,
+        },
+  )
+}

package/src/components/agent/use-path-links.ts

@@ -1,4 +1,5 @@
 import { useEffect, type RefObject } from 'react'
+import { parseFileLink } from '../../lib/file-link.ts'
 
 export type PathHit = { path: string; line?: number }
 
@@ -119,11 +120,5 @@ export function usePathLinks({
 }
 
 export function resolveAgainstCwd(path: string, cwd: string | undefined): string {
-  if (path.startsWith('/')) {
-    return path
-  }
-  if (!cwd) {
-    return path
-  }
-  return `${cwd.replace(/\/$/, '')}/${path.replace(/^\.\//, '')}`
+  return parseFileLink(path, cwd)?.path ?? path
 }

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/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,8 @@ 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 { Conversation, ConversationContent, ConversationScrollButton, type ConversationProps } from './components/agent/Conversation.tsx'
 export { Message, MessageContent, type MessageProps } from './components/agent/Message.tsx'
 export {
@@ -86,7 +88,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,

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/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