@alumbwe/anvil 1.0.0

package/src/components/tools/suggest-followups.tsx

@@ -0,0 +1,369 @@
+import { TextAttributes } from '@opentui/core'
+import { useCallback, useEffect, useState } from 'react'
+
+import { defineToolComponent } from './types'
+import { useTerminalDimensions } from '../../hooks/use-terminal-dimensions'
+import { useTheme } from '../../hooks/use-theme'
+import { getLatestFollowupToolCallId, useChatStore } from '../../state/chat-store'
+import { useFreebuffSessionStore } from '../../state/freebuff-session-store'
+import { IS_FREEBUFF } from '../../utils/constants'
+import { Button } from '../button'
+
+import type { ToolRenderConfig } from './types'
+import type { SuggestedFollowup } from '../../types/store'
+
+const EMPTY_CLICKED_SET = new Set<number>()
+const MIN_LABEL_COLUMN_WIDTH = 12
+const MAX_LABEL_COLUMN_WIDTH = 60
+/** Minimum terminal width to show the prompt description on hover */
+const MIN_WIDTH_FOR_DESCRIPTION = 80
+
+interface FollowupLineProps {
+  followup: SuggestedFollowup
+  index: number
+  isClicked: boolean
+  isHovered: boolean
+  onSendFollowup: (prompt: string, index: number) => void
+  onHover: (index: number | null) => void
+  disabled?: boolean
+  /** Width of the label column (for fixed-width alignment) */
+  labelColumnWidth: number
+}
+
+const FollowupLine = ({
+  followup,
+  index,
+  isClicked,
+  isHovered,
+  onSendFollowup,
+  onHover,
+  disabled,
+  labelColumnWidth,
+}: FollowupLineProps) => {
+  const theme = useTheme()
+  const { terminalWidth } = useTerminalDimensions()
+
+  const handleClick = useCallback(() => {
+    if (!disabled) {
+      onSendFollowup(followup.prompt, index)
+    }
+  }, [followup.prompt, index, onSendFollowup, disabled])
+
+  const handleMouseOver = useCallback(() => onHover(index), [onHover, index])
+  const handleMouseOut = useCallback(() => onHover(null), [onHover])
+
+  // Compute effective hover state declaratively
+  // Show hover effects if actually hovered AND not disabled AND not already clicked
+  const showHoverState = isHovered && !disabled && !isClicked
+
+  const hasLabel = Boolean(followup.label)
+  const displayText = hasLabel ? followup.label : followup.prompt
+
+  // Show description when hovered, has a label, and terminal is wide enough
+  const showDescription =
+    showHoverState && hasLabel && terminalWidth >= MIN_WIDTH_FOR_DESCRIPTION
+
+  // Calculate truncated prompt with ellipsis only when needed
+  const truncatedPrompt = showDescription
+    ? (() => {
+        const availableWidth = Math.max(0, terminalWidth - labelColumnWidth - 4)
+        return followup.prompt.length > availableWidth
+          ? followup.prompt.slice(0, availableWidth - 1) + '…'
+          : followup.prompt
+      })()
+    : ''
+
+  // Determine colors based on state
+  // When hovered, use primary color (violet) for both arrow and title
+  const iconColor = isClicked
+    ? theme.success
+    : showHoverState
+      ? theme.primary
+      : theme.muted
+  const labelColor = isClicked
+    ? theme.muted
+    : showHoverState
+      ? theme.primary
+      : theme.foreground
+
+  // Calculate padding spaces needed to align descriptions (only when showing description)
+  const labelLength = (displayText ?? '').length
+  const paddingSpaces = showDescription
+    ? ' '.repeat(Math.max(0, labelColumnWidth - 2 - labelLength)) // -2 for "→ " prefix
+    : ''
+
+  return (
+    <box style={{ flexDirection: 'column' }}>
+      {/* Row layout: clickable label + non-clickable description */}
+      <box style={{ flexDirection: 'row', width: '100%' }}>
+        {/* Clickable label area - only the text itself is clickable */}
+        <Button
+          onClick={handleClick}
+          onMouseOver={handleMouseOver}
+          onMouseOut={handleMouseOut}
+          style={{
+            flexShrink: 0,
+            flexGrow: 0,
+            backgroundColor: showHoverState ? theme.surface : undefined,
+          }}
+        >
+          <text style={{ wrapMode: hasLabel ? 'none' : 'word' }}>
+            <span fg={iconColor}>{isClicked ? '✓' : '→'}</span>
+            <span
+              fg={labelColor}
+              attributes={showHoverState ? TextAttributes.BOLD : undefined}
+            >
+              {' '}
+              {displayText}
+            </span>
+          </text>
+        </Button>
+        {/* Flexible description column - NOT clickable, with padding for alignment */}
+        {showDescription && hasLabel && (
+          <box style={{ flexGrow: 1 }}>
+            <text style={{ wrapMode: 'none' }}>
+              <span fg={theme.muted} attributes={TextAttributes.ITALIC}>
+                {paddingSpaces}{truncatedPrompt}
+              </span>
+            </text>
+          </box>
+        )}
+      </box>
+    </box>
+  )
+}
+
+interface SuggestFollowupsItemProps {
+  toolCallId: string
+  followups: SuggestedFollowup[]
+  onSendFollowup: (prompt: string, index: number) => void
+}
+
+interface PastFollowupItemProps {
+  followup: SuggestedFollowup
+  isClicked: boolean
+}
+
+const PastFollowupItem = ({ followup, isClicked }: PastFollowupItemProps) => {
+  const theme = useTheme()
+  const displayLabel = followup.label || followup.prompt
+  const showFullPrompt = followup.label && followup.label !== followup.prompt
+
+  return (
+    <box style={{ flexDirection: 'column', marginLeft: 2 }}>
+      <text>
+        <span fg={isClicked ? theme.success : theme.muted}>
+          {isClicked ? '✓' : '→'}
+        </span>
+        <span fg={isClicked ? theme.muted : theme.foreground}>
+          {' '}
+          {displayLabel}
+        </span>
+      </text>
+      {showFullPrompt && (
+        <text style={{ marginLeft: 2 }}>
+          <span fg={theme.muted} attributes={TextAttributes.ITALIC}>
+            {followup.prompt}
+          </span>
+        </text>
+      )}
+    </box>
+  )
+}
+
+interface PastFollowupsToggleProps {
+  toolCallId: string
+  followups: SuggestedFollowup[]
+}
+
+const PastFollowupsToggle = ({
+  toolCallId,
+  followups,
+}: PastFollowupsToggleProps) => {
+  const theme = useTheme()
+  const [isExpanded, setIsExpanded] = useState(false)
+  const clickedIndices = useChatStore(
+    (state) => state.clickedFollowupsMap.get(toolCallId) ?? EMPTY_CLICKED_SET,
+  )
+
+  const handleToggle = useCallback(() => {
+    setIsExpanded((prev) => !prev)
+  }, [])
+
+  const toggleIndicator = isExpanded ? '▾' : '▸'
+
+  return (
+    <box style={{ flexDirection: 'column' }}>
+      <Button onClick={handleToggle}>
+        <text>
+          <span fg={theme.muted}>{toggleIndicator}</span>
+          <span fg={theme.muted} attributes={TextAttributes.ITALIC}>
+            {' '}
+            Previously suggested followups
+          </span>
+        </text>
+      </Button>
+      {isExpanded && (
+        <box style={{ flexDirection: 'column', marginTop: 0 }}>
+          {followups.map((followup, index) => (
+            <PastFollowupItem
+              key={`past-followup-${index}`}
+              followup={followup}
+              isClicked={clickedIndices.has(index)}
+            />
+          ))}
+        </box>
+      )}
+    </box>
+  )
+}
+
+const SuggestFollowupsItem = ({
+  toolCallId,
+  followups,
+  onSendFollowup,
+}: SuggestFollowupsItemProps) => {
+  const theme = useTheme()
+  const inputFocused = useChatStore((state) => state.inputFocused)
+  const isFreebuffSessionOver = useFreebuffSessionStore(
+    (state) => IS_FREEBUFF && state.session?.status === 'ended',
+  )
+  const setSuggestedFollowups = useChatStore(
+    (state) => state.setSuggestedFollowups,
+  )
+  const latestFollowupToolCallId = useChatStore((state) =>
+    getLatestFollowupToolCallId(state.messages),
+  )
+  const clickedIndices = useChatStore(
+    (state) => state.clickedFollowupsMap.get(toolCallId) ?? EMPTY_CLICKED_SET,
+  )
+  const currentSuggestedFollowups = useChatStore(
+    (state) => state.suggestedFollowups,
+  )
+
+  const isActive = latestFollowupToolCallId === toolCallId
+
+  useEffect(() => {
+    if (!isActive) return
+
+    const hasSameTool = currentSuggestedFollowups?.toolCallId === toolCallId
+    const hasSameFollowups =
+      hasSameTool &&
+      currentSuggestedFollowups?.followups.length === followups.length &&
+      currentSuggestedFollowups.followups.every((f, idx) => {
+        const next = followups[idx]
+        return f?.prompt === next?.prompt && f?.label === next?.label
+      })
+    const hasSameClicks =
+      hasSameTool &&
+      currentSuggestedFollowups?.clickedIndices.size === clickedIndices.size &&
+      Array.from(currentSuggestedFollowups.clickedIndices).every((idx) =>
+        clickedIndices.has(idx),
+      )
+
+    if (hasSameFollowups && hasSameClicks) return
+
+    // Track the currently active followups set so we can persist clicked state and avoid races
+    setSuggestedFollowups({
+      toolCallId,
+      followups,
+      clickedIndices: new Set(clickedIndices),
+    })
+  }, [
+    clickedIndices,
+    currentSuggestedFollowups,
+    followups,
+    isActive,
+    setSuggestedFollowups,
+    toolCallId,
+  ])
+
+  // Track which item is hovered (for passing to children)
+  const [hoveredIndex, setHoveredIndex] = useState<number | null>(null)
+
+  // For past messages, show collapsed toggle view
+  if (!isActive) {
+    return <PastFollowupsToggle toolCallId={toolCallId} followups={followups} />
+  }
+
+  // Calculate label column width for alignment across all followups
+  // Width = "→ " (2 chars) + max label/prompt length + "  " spacing (2 chars)
+  const maxDisplayLength = Math.max(
+    0,
+    ...followups.map((f) => (f.label ?? f.prompt).length),
+  )
+  const labelColumnWidth = Math.min(
+    MAX_LABEL_COLUMN_WIDTH,
+    Math.max(MIN_LABEL_COLUMN_WIDTH, 2 + maxDisplayLength + 2),
+  ) // "→ " + label/prompt + "  "
+
+  return (
+    <box style={{ flexDirection: 'column' }}>
+      <text style={{ fg: theme.muted }}>Suggested followups:</text>
+      <box style={{ flexDirection: 'column' }}>
+        {followups.map((followup, index) => (
+          <FollowupLine
+            key={`followup-${index}`}
+            followup={followup}
+            index={index}
+            isClicked={clickedIndices.has(index)}
+            isHovered={hoveredIndex === index}
+            onSendFollowup={onSendFollowup}
+            onHover={setHoveredIndex}
+            disabled={!inputFocused || isFreebuffSessionOver}
+            labelColumnWidth={labelColumnWidth}
+          />
+        ))}
+      </box>
+    </box>
+  )
+}
+
+/**
+ * UI component for suggest_followups tool.
+ * Displays clickable cards that send the followup prompt as a user message when clicked.
+ */
+export const SuggestFollowupsComponent = defineToolComponent({
+  toolName: 'suggest_followups',
+
+  render(toolBlock, _theme, options): ToolRenderConfig {
+    const { input, toolCallId } = toolBlock
+
+    // Extract followups from input
+    let followups: SuggestedFollowup[] = []
+
+    if (Array.isArray(input?.followups)) {
+      followups = input.followups.filter(
+        (f: unknown): f is SuggestedFollowup =>
+          typeof f === 'object' &&
+          f !== null &&
+          typeof (f as SuggestedFollowup).prompt === 'string',
+      )
+    }
+
+    if (followups.length === 0) {
+      return { content: null }
+    }
+
+    // The actual click handling is done in chat.tsx via the global handler
+    // Here we just pass a placeholder that will be replaced
+    const handleSendFollowup = (prompt: string, index: number) => {
+      // This gets called from the FollowupCard component
+      // The actual logic is handled via the global followup handler
+      const event = new CustomEvent('anvil:send-followup', {
+        detail: { prompt, index, toolCallId },
+      })
+      globalThis.dispatchEvent(event)
+    }
+
+    return {
+      content: (
+        <SuggestFollowupsItem
+          toolCallId={toolCallId}
+          followups={followups}
+          onSendFollowup={handleSendFollowup}
+        />
+      ),
+    }
+  },
+})

package/src/components/tools/task-completed.tsx

@@ -0,0 +1,16 @@
+import { defineToolComponent } from './types'
+
+import type { ToolRenderConfig } from './types'
+
+/**
+ * UI component for task_completed tool.
+ */
+export const TaskCompleteComponent = defineToolComponent({
+  toolName: 'task_completed',
+
+  render(): ToolRenderConfig {
+    return {
+      content: null,
+    }
+  },
+})

package/src/components/tools/tool-call-item.tsx

@@ -0,0 +1,273 @@
+import { TextAttributes } from '@opentui/core'
+import React, { type ReactNode } from 'react'
+import stringWidth from 'string-width'
+
+import { useTheme } from '../../hooks/use-theme'
+import { Button } from '../button'
+
+import type { ChatTheme } from '../../types/theme-system'
+
+interface ToolCallItemProps {
+  name: string
+  content: ReactNode
+  isCollapsed: boolean
+  isStreaming: boolean
+  streamingPreview: string
+  finishedPreview: string
+  onToggle?: () => void
+  titleSuffix?: string
+  dense?: boolean
+}
+
+const isTextRenderable = (value: ReactNode): boolean => {
+  if (value === null || value === undefined || typeof value === 'boolean') {
+    return false
+  }
+
+  if (typeof value === 'string' || typeof value === 'number') {
+    return true
+  }
+
+  if (Array.isArray(value)) {
+    return value.every((child) => isTextRenderable(child))
+  }
+
+  if (React.isValidElement(value)) {
+    const elProps = value.props as Record<string, unknown>
+    if (value.type === React.Fragment) {
+      return isTextRenderable(elProps.children as ReactNode)
+    }
+
+    if (typeof value.type === 'string') {
+      if (
+        value.type === 'span' ||
+        value.type === 'strong' ||
+        value.type === 'em'
+      ) {
+        return isTextRenderable(elProps.children as ReactNode)
+      }
+
+      return false
+    }
+  }
+
+  return false
+}
+
+const renderExpandedContent = (
+  value: ReactNode,
+  theme: ChatTheme,
+  getAttributes: (extra?: number) => number | undefined,
+): ReactNode => {
+  if (
+    value === null ||
+    value === undefined ||
+    value === false ||
+    value === true
+  ) {
+    return null
+  }
+
+  if (isTextRenderable(value)) {
+    return (
+      <text
+        fg={theme.foreground}
+        key="tool-expanded-text"
+        attributes={getAttributes()}
+      >
+        {value}
+      </text>
+    )
+  }
+
+  if (React.isValidElement(value)) {
+    if (value.key === null || value.key === undefined) {
+      return (
+        <box
+          key="tool-expanded-node"
+          style={{ flexDirection: 'column', gap: 0 }}
+        >
+          {value}
+        </box>
+      )
+    }
+    return value
+  }
+
+  if (Array.isArray(value)) {
+    return (
+      <box
+        key="tool-expanded-array"
+        style={{ flexDirection: 'column', gap: 0 }}
+      >
+        {value.map((child, idx) => (
+          <box
+            key={`tool-expanded-array-${idx}`}
+            style={{ flexDirection: 'column', gap: 0 }}
+          >
+            {child}
+          </box>
+        ))}
+      </box>
+    )
+  }
+
+  return (
+    <box
+      key="tool-expanded-unknown"
+      style={{ flexDirection: 'column', gap: 0 }}
+    >
+      {value}
+    </box>
+  )
+}
+
+interface SimpleToolCallItemProps {
+  name: string
+  /** Description - can be a string or ReactNode for rich formatting */
+  description: string | ReactNode
+  descriptionColor?: string
+}
+
+export const SimpleToolCallItem = ({
+  name,
+  description,
+  descriptionColor,
+}: SimpleToolCallItemProps) => {
+  const theme = useTheme()
+  const bulletChar = '• '
+
+  return (
+    <box style={{ flexDirection: 'row', alignItems: 'center', width: '100%' }}>
+      <text style={{ wrapMode: 'word' }}>
+        <span fg={theme.foreground}>{bulletChar}</span>
+        <span fg={theme.foreground} attributes={TextAttributes.BOLD}>
+          {name}
+        </span>
+        <span fg={theme.foreground}> </span>
+        {typeof description === 'string' ? (
+          <span fg={descriptionColor ?? theme.foreground}>{description}</span>
+        ) : (
+          description
+        )}
+      </text>
+    </box>
+  )
+}
+
+export const ToolCallItem = ({
+  name,
+  content,
+  isCollapsed,
+  isStreaming,
+  streamingPreview,
+  finishedPreview,
+  onToggle,
+  titleSuffix,
+  dense = false,
+}: ToolCallItemProps) => {
+  const theme = useTheme()
+
+  const baseTextAttributes = theme.messageTextAttributes ?? 0
+  const getAttributes = (extra: number = 0): number | undefined => {
+    const combined = baseTextAttributes | extra
+    return combined === 0 ? undefined : combined
+  }
+
+  const isExpanded = !isCollapsed
+  const bulletChar = '• '
+  const toggleIndicator = onToggle ? (isCollapsed ? '▸ ' : '▾ ') : ''
+  const toggleLabel = onToggle ? toggleIndicator : bulletChar
+  // Width in cells of the toggle label (toggle arrow or bullet). Used to align
+  // expanded content directly under the toggle icon.
+  const toggleIndent = stringWidth(toggleLabel)
+  const collapsedPreviewText = isStreaming ? streamingPreview : finishedPreview
+  const showCollapsedPreview = collapsedPreviewText.length > 0
+
+  return (
+    <box style={{ flexDirection: 'column', gap: 0, width: '100%' }}>
+      <box
+        style={{
+          flexDirection: 'column',
+          gap: 0,
+          paddingLeft: 0,
+          paddingRight: 0,
+          paddingTop: 0,
+          paddingBottom: 0,
+          width: '100%',
+        }}
+      >
+        <Button
+          style={{
+            flexDirection: 'row',
+            alignItems: 'center',
+            paddingLeft: 0,
+            paddingRight: 0,
+            paddingTop: 0,
+            paddingBottom: 0,
+            width: '100%',
+          }}
+          onClick={onToggle}
+        >
+          <text style={{ wrapMode: 'none' }}>
+            <span
+              fg={theme.foreground}
+              attributes={isExpanded ? TextAttributes.BOLD : undefined}
+            >
+              {toggleLabel}
+            </span>
+            <span fg={theme.foreground} attributes={TextAttributes.BOLD}>
+              {name}
+            </span>
+            {titleSuffix ? (
+              <span fg={theme.foreground} attributes={TextAttributes.BOLD}>
+                {` ${titleSuffix}`}
+              </span>
+            ) : null}
+            {isStreaming ? (
+              <span fg={theme.primary} attributes={TextAttributes.DIM}>
+                {' running'}
+              </span>
+            ) : null}
+          </text>
+        </Button>
+
+        {isCollapsed ? (
+          showCollapsedPreview ? (
+            <box
+              style={{
+                paddingLeft: 0,
+                paddingRight: 0,
+                paddingTop: 0,
+                paddingBottom: 0,
+                width: '100%',
+              }}
+            >
+              <text
+                fg={isStreaming ? theme.foreground : theme.muted}
+                attributes={getAttributes(TextAttributes.ITALIC)}
+                style={{ wrapMode: 'word' }}
+              >
+                {collapsedPreviewText}
+              </text>
+            </box>
+          ) : null
+        ) : (
+          <box
+            style={{
+              flexDirection: 'column',
+              gap: 0,
+              // Indent expanded content underneath the toggle icon
+              paddingLeft: toggleIndent,
+              paddingRight: dense ? 0 : toggleIndent,
+              paddingTop: 0,
+              paddingBottom: 0,
+            }}
+          >
+            {renderExpandedContent(content, theme, getAttributes)}
+          </box>
+        )}
+      </box>
+    </box>
+  )
+}

package/src/components/tools/types.ts

@@ -0,0 +1,55 @@
+import type { ContentBlock } from '../../types/chat'
+import type { ChatTheme } from '../../types/theme-system'
+import type { ToolName } from '@anvil/sdk'
+import type { ReactNode } from 'react'
+
+export type ToolBlock = Extract<ContentBlock, { type: 'tool' }>
+
+export type ToolRenderOptions = {
+  availableWidth: number
+  indentationOffset: number
+  previewPrefix?: string
+  labelWidth: number
+}
+
+export type ToolRenderConfig = {
+  /** Optional path to display in the tool header */
+  path?: string
+  /** Custom content to render in the tool body */
+  content?: ReactNode
+  /** Preview text to show when the tool is collapsed */
+  collapsedPreview?: string
+}
+
+/**
+ * Base interface for tool-specific UI components.
+ * Implement this interface to create a custom renderer for a specific tool.
+ */
+export interface ToolComponent<T extends ToolName = ToolName> {
+  /** The tool name this component handles */
+  toolName: T
+
+  /**
+   * Render function that returns configuration for how to display this tool.
+   *
+   * @param toolBlock - The tool block data containing input/output
+   * @param theme - The current chat theme
+   * @param options - Rendering options like width and indentation
+   * @returns Configuration for rendering the tool, or null to use default rendering
+   */
+  render(
+    toolBlock: ToolBlock & { toolName: T },
+    theme: ChatTheme,
+    options: ToolRenderOptions,
+  ): ToolRenderConfig
+}
+
+/**
+ * Type-safe tool component definition.
+ * Use this helper to create tool components with full type inference.
+ */
+export function defineToolComponent<T extends ToolName>(
+  component: ToolComponent<T>,
+): ToolComponent<T> {
+  return component
+}