@andypai/orb 0.1.1

package/src/ui/hooks/useAnimationFrame.ts

@@ -0,0 +1,33 @@
+import { useEffect, useState } from 'react'
+
+interface UseAnimationFrameOptions {
+  fps?: number
+  active?: boolean
+}
+
+/**
+ * Custom hook for frame-based animation with configurable FPS.
+ * Returns an incrementing frame counter that triggers re-renders at the specified rate.
+ * Uses setInterval for Node.js compatibility (no requestAnimationFrame in terminal).
+ */
+export function useAnimationFrame({
+  fps = 30,
+  active = true,
+}: UseAnimationFrameOptions = {}): number {
+  const [frame, setFrame] = useState(0)
+
+  useEffect(() => {
+    if (!active) return
+
+    const intervalMs = Math.floor(1000 / fps)
+    const intervalId = setInterval(() => {
+      setFrame((f) => f + 1)
+    }, intervalMs)
+
+    return () => {
+      clearInterval(intervalId)
+    }
+  }, [fps, active])
+
+  return frame
+}

package/src/ui/hooks/useConversation.ts

@@ -0,0 +1,195 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import type { OutboundFrame } from '../../pipeline/transports/types'
+import type { RunResult } from '../../pipeline/task'
+import { saveSession } from '../../services/session'
+import {
+  ANTHROPIC_MODELS,
+  type AgentSession,
+  type AnthropicModel,
+  type AppConfig,
+  type AppState,
+  type HistoryEntry,
+  type LlmModelId,
+  type SavedSession,
+  type TTSErrorType,
+} from '../../types'
+
+interface UseConversationConfig {
+  config: AppConfig
+  initialSession?: SavedSession | null
+  taskState: AppState
+}
+
+export function useConversation({ config, initialSession, taskState }: UseConversationConfig) {
+  const sessionMatchesProvider = initialSession?.llmProvider === config.llmProvider
+  const initialHistory = initialSession?.history ?? []
+  const initialModel =
+    (sessionMatchesProvider ? initialSession?.llmModel : undefined) ?? config.llmModel
+  const initialAgentSession = sessionMatchesProvider ? initialSession?.agentSession : undefined
+
+  const [completedTurns, setCompletedTurns] = useState<HistoryEntry[]>(initialHistory)
+  const [liveTurn, setLiveTurn] = useState<HistoryEntry | null>(null)
+  const [ttsError, setTtsError] = useState<{ type: TTSErrorType; message: string } | null>(null)
+  const [activeModel, setActiveModel] = useState<LlmModelId>(initialModel)
+
+  const liveTurnRef = useRef<HistoryEntry | null>(null)
+  const activeEntryIdRef = useRef<string | null>(null)
+  const agentSessionRef = useRef<AgentSession | undefined>(initialAgentSession)
+  const pendingSaveRef = useRef(false)
+
+  /** Update both ref (synchronous, for archive guards) and state (async, for render). */
+  const updateLiveTurn = useCallback((turn: HistoryEntry | null) => {
+    liveTurnRef.current = turn
+    setLiveTurn(turn)
+  }, [])
+
+  const getHistorySnapshot = useCallback(
+    () => [...completedTurns, ...(liveTurnRef.current ? [liveTurnRef.current] : [])],
+    [completedTurns],
+  )
+
+  const persistSession = useCallback(
+    async (modelOverride?: LlmModelId, historyOverride?: HistoryEntry[]) => {
+      const history = historyOverride ?? getHistorySnapshot()
+      const payload: SavedSession = {
+        version: 2,
+        projectPath: config.projectPath,
+        llmProvider: config.llmProvider,
+        llmModel: modelOverride ?? activeModel,
+        agentSession: agentSessionRef.current,
+        lastModified: new Date().toISOString(),
+        history,
+      }
+
+      try {
+        await saveSession(payload)
+      } catch (err) {
+        console.warn('Failed to save session:', err)
+      }
+    },
+    [activeModel, config.llmProvider, config.projectPath, getHistorySnapshot],
+  )
+
+  useEffect(() => {
+    if (!pendingSaveRef.current) return
+    if (taskState !== 'idle') return
+    pendingSaveRef.current = false
+    void persistSession()
+  }, [completedTurns, persistSession, taskState])
+
+  const startEntry = useCallback((query: string) => {
+    const trimmed = query.trim()
+    if (!trimmed) return null
+
+    // Archive any existing live turn (safety net for edge cases)
+    const existingLiveTurn = liveTurnRef.current
+    if (existingLiveTurn !== null) {
+      liveTurnRef.current = null
+      setCompletedTurns((prev) => [...prev, existingLiveTurn])
+    }
+
+    const entryId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+    const newTurn: HistoryEntry = {
+      id: entryId,
+      question: trimmed,
+      toolCalls: [],
+      answer: '',
+      error: null,
+    }
+
+    activeEntryIdRef.current = entryId
+    updateLiveTurn(newTurn)
+    setTtsError(null)
+
+    return { entryId, query: trimmed }
+  }, [])
+
+  const handleFrame = useCallback(
+    (frame: OutboundFrame) => {
+      if (!liveTurnRef.current) return
+      const cur = liveTurnRef.current
+
+      switch (frame.kind) {
+        case 'agent-text-delta':
+          updateLiveTurn({ ...cur, answer: frame.accumulatedText })
+          break
+
+        case 'agent-text-complete':
+          updateLiveTurn({ ...cur, answer: frame.text })
+          break
+
+        case 'tool-call-start':
+          updateLiveTurn({ ...cur, toolCalls: [...cur.toolCalls, frame.toolCall] })
+          break
+
+        case 'tool-call-result':
+          updateLiveTurn({
+            ...cur,
+            toolCalls: cur.toolCalls.map((tc) =>
+              tc.index === frame.toolIndex
+                ? { ...tc, status: frame.status, result: frame.result }
+                : tc,
+            ),
+          })
+          break
+
+        case 'agent-error':
+          updateLiveTurn({ ...cur, error: frame.error.message })
+          break
+
+        case 'tts-error':
+          setTtsError({ type: frame.errorType, message: frame.message })
+          break
+      }
+    },
+    [updateLiveTurn],
+  )
+
+  const handleRunComplete = useCallback(
+    (result: RunResult) => {
+      // Guard: only archive the turn this run belongs to.
+      // If startEntry already replaced it with a new turn, skip.
+      if (liveTurnRef.current === null) return
+      if (activeEntryIdRef.current !== result.entryId) return
+
+      if (result.session) {
+        agentSessionRef.current = result.session
+      }
+
+      const turnToArchive = liveTurnRef.current
+      activeEntryIdRef.current = null
+      setCompletedTurns((prev) => [...prev, turnToArchive])
+      updateLiveTurn(null)
+
+      if (!result.cancelled) {
+        pendingSaveRef.current = true
+      }
+    },
+    [updateLiveTurn],
+  )
+
+  const cycleModel = useCallback(() => {
+    if (config.llmProvider !== 'anthropic') return
+
+    const currentIndex = ANTHROPIC_MODELS.indexOf(activeModel as AnthropicModel)
+    const nextIndex = currentIndex === -1 ? 0 : (currentIndex + 1) % ANTHROPIC_MODELS.length
+    const nextModel = ANTHROPIC_MODELS[nextIndex] ?? ANTHROPIC_MODELS[0]
+    setActiveModel(nextModel)
+
+    void persistSession(nextModel, getHistorySnapshot())
+  }, [activeModel, config.llmProvider, getHistorySnapshot, persistSession])
+
+  return {
+    liveTurn,
+    activeModel,
+    completedTurns,
+    handleFrame,
+    handleRunComplete,
+    initialAgentSession,
+    initialModel,
+    startEntry,
+    ttsError,
+    cycleModel,
+  }
+}

package/src/ui/hooks/useKeyboardShortcuts.ts

@@ -0,0 +1,57 @@
+import { useInput } from 'ink'
+
+import type { AppState } from '../../types'
+
+interface UseKeyboardShortcutsConfig {
+  canCycleModel: boolean
+  onCancel(): void
+  onCycleModel(): void
+  onToggleDetailMode(): void
+  state: AppState
+}
+
+export function useKeyboardShortcuts({
+  canCycleModel,
+  onCancel,
+  onCycleModel,
+  onToggleDetailMode,
+  state,
+}: UseKeyboardShortcutsConfig) {
+  useInput(
+    (input, key) => {
+      if (key.escape || (key.ctrl && input === 's')) {
+        onCancel()
+      }
+    },
+    { isActive: state !== 'idle' },
+  )
+
+  useInput(
+    (input, key) => {
+      if (key.ctrl && input === 'o') {
+        onToggleDetailMode()
+      }
+    },
+    { isActive: true },
+  )
+
+  useInput(
+    (input, key) => {
+      const isShiftTab =
+        (key.shift && key.tab) || input === '\u001b[Z' || (key.shift && input === '\t')
+      if (isShiftTab) {
+        onCycleModel()
+      }
+    },
+    { isActive: canCycleModel },
+  )
+
+  useInput(
+    (input, key) => {
+      if (key.ctrl && input === 'c') {
+        process.exit(0)
+      }
+    },
+    { isActive: true },
+  )
+}

package/src/ui/hooks/usePipeline.ts

@@ -0,0 +1,83 @@
+import { useCallback, useEffect, useMemo, useState } from 'react'
+
+import { createPipelineTask } from '../../pipeline/task'
+import type { RunResult, TaskState } from '../../pipeline/task'
+import { createTerminalTextTransport } from '../../pipeline/transports/terminal-text'
+import type { OutboundFrame, Transport } from '../../pipeline/transports/types'
+import type { AgentSession, AppConfig } from '../../types'
+
+interface PendingRun {
+  entryId: string
+  query: string
+}
+
+interface UsePipelineConfig {
+  config: AppConfig
+  activeModel: string
+  initialModel: string
+  initialSession?: AgentSession
+  onFrame(frame: OutboundFrame): void
+  onRunComplete(result: RunResult): void
+  onStateChange(state: TaskState): void
+  startEntry(query: string): PendingRun | null
+}
+
+export function usePipeline({
+  config,
+  activeModel,
+  initialModel,
+  initialSession,
+  onFrame,
+  onRunComplete,
+  onStateChange,
+  startEntry,
+}: UsePipelineConfig) {
+  const [state, setState] = useState<TaskState>('idle')
+  const activeConfig = useMemo(() => ({ ...config, llmModel: activeModel }), [config, activeModel])
+
+  const { task, transport } = useMemo(() => {
+    const nextTransport = createTerminalTextTransport()
+    const nextTask = createPipelineTask({
+      appConfig: { ...config, llmModel: initialModel },
+      session: initialSession,
+      transport: nextTransport,
+    })
+
+    return {
+      task: nextTask,
+      transport: nextTransport as Transport,
+    }
+  }, []) as { task: ReturnType<typeof createPipelineTask>; transport: Transport }
+
+  useEffect(() => {
+    task.updateConfig(activeConfig)
+  }, [task, activeConfig])
+
+  useEffect(
+    () =>
+      task.onStateChange((nextState) => {
+        setState(nextState)
+        onStateChange(nextState)
+      }),
+    [onStateChange, task],
+  )
+
+  useEffect(() => transport.onOutbound(onFrame), [onFrame, transport])
+
+  const cancel = useCallback(() => {
+    task.cancel()
+  }, [task])
+
+  const submit = useCallback(
+    async (query: string) => {
+      const pendingRun = startEntry(query)
+      if (!pendingRun) return
+
+      const result = await task.run(pendingRun.query, pendingRun.entryId)
+      onRunComplete(result)
+    },
+    [onRunComplete, startEntry, task],
+  )
+
+  return { cancel, state, submit }
+}

package/src/ui/hooks/useTerminalSize.ts

@@ -0,0 +1,37 @@
+import { useState, useEffect } from 'react'
+
+interface TerminalSize {
+  columns: number
+  rows: number
+}
+
+const DEFAULT_SIZE: TerminalSize = { columns: 80, rows: 24 }
+
+function getCurrentSize(): TerminalSize {
+  if (!process.stdout.isTTY) {
+    return DEFAULT_SIZE
+  }
+  return {
+    columns: process.stdout.columns ?? DEFAULT_SIZE.columns,
+    rows: process.stdout.rows ?? DEFAULT_SIZE.rows,
+  }
+}
+
+export function useTerminalSize(): TerminalSize {
+  const [size, setSize] = useState<TerminalSize>(getCurrentSize)
+
+  useEffect(() => {
+    if (!process.stdout.isTTY) return
+
+    const handleResize = () => {
+      setSize(getCurrentSize())
+    }
+
+    process.stdout.on('resize', handleResize)
+    return () => {
+      process.stdout.off('resize', handleResize)
+    }
+  }, [])
+
+  return size
+}

package/src/ui/utils/markdown.ts

@@ -0,0 +1,89 @@
+/**
+ * Strip markdown formatting for clean terminal display.
+ * Keeps code blocks/inline code visible since they're meaningful in a code context.
+ */
+export function stripMarkdown(text: string): string {
+  const preserved: string[] = []
+
+  function preserve(input: string, pattern: RegExp): string {
+    return input.replace(pattern, (match) => {
+      const token = `@@PRESERVE_${preserved.length}@@`
+      preserved.push(match)
+      return token
+    })
+  }
+
+  function restore(input: string): string {
+    return input.replace(/@@PRESERVE_(\d+)@@/g, (_, index) => preserved[Number(index)] ?? '')
+  }
+
+  const withoutCode = preserve(preserve(text, /```[\s\S]*?```/g), /`[^`]*`/g)
+
+  const stripped = withoutCode
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1') // Links
+    .replace(/\*\*([^*]+)\*\*/g, '$1') // Bold **
+    .replace(/__([^_]+)__/g, '$1') // Bold __
+    .replace(/\*([^*]+)\*/g, '$1') // Italic *
+    .replace(/(?<!\w)_([^_]+)_(?!\w)/g, '$1') // Italic _
+    .replace(/~~([^~]+)~~/g, '$1') // Strikethrough
+    .replace(/^#{1,6}\s*/gm, '') // Headers
+    .replace(/^\s*>+\s?/gm, '') // Blockquotes
+    .replace(/^\s*[-*]\s+/gm, '') // Unordered lists
+    .replace(/^\s*\d+\.\s+/gm, '') // Ordered lists
+    .replace(/^[-*]{3,}\s*$/gm, '') // Horizontal rules
+
+  return restore(stripped)
+}
+
+/**
+ * Replace delimited sections with a placeholder.
+ * Handles both paired delimiters (open/close) and single-character delimiters.
+ */
+function replaceDelimited(
+  input: string,
+  openDelimiter: string,
+  closeDelimiter: string,
+  replacement: string,
+): string {
+  let result = ''
+  let cursor = 0
+
+  while (cursor < input.length) {
+    const start = input.indexOf(openDelimiter, cursor)
+    if (start === -1) {
+      result += input.slice(cursor)
+      break
+    }
+
+    const searchFrom = start + openDelimiter.length
+    const end = input.indexOf(closeDelimiter, searchFrom)
+
+    result += input.slice(cursor, start) + replacement
+
+    if (end === -1) {
+      result += input.slice(searchFrom)
+      break
+    }
+
+    cursor = end + closeDelimiter.length
+  }
+
+  return result
+}
+
+/**
+ * Clean text for speech synthesis.
+ * Removes code blocks/inline code (replacing with spoken placeholders),
+ * strips markdown, and collapses whitespace.
+ */
+export function cleanTextForSpeech(text: string): string {
+  const withoutCodeBlocks = replaceDelimited(text, '```', '```', ' code block ')
+  const withoutInlineCode = replaceDelimited(withoutCodeBlocks, '`', '`', ' code ')
+
+  return withoutInlineCode
+    .split('\n')
+    .map((line) => stripMarkdown(line))
+    .join('\n')
+    .replace(/\s+/g, ' ')
+    .trim()
+}

package/src/ui/utils/model-label.ts

@@ -0,0 +1,20 @@
+import type { AnthropicModel, LlmModelId, LlmProvider } from '../../types'
+import { ANTHROPIC_MODELS } from '../../types'
+
+export const MODEL_LABELS: Record<AnthropicModel, string> = {
+  'claude-haiku-4-5-20251001': 'Haiku',
+  'claude-sonnet-4-6': 'Sonnet 4.6',
+  'claude-opus-4-6': 'Opus 4.6',
+  'claude-opus-4-5-20251101': 'Opus 4.5',
+  'claude-sonnet-4-5-20250929': 'Sonnet 4.5',
+  'claude-opus-4-1-20250805': 'Opus 4.1',
+  'claude-opus-4-20250514': 'Opus 4',
+  'claude-sonnet-4-20250514': 'Sonnet 4',
+  'claude-3-haiku-20240307': 'Haiku 3',
+}
+
+export function formatModelLabel(provider: LlmProvider, model: LlmModelId): string {
+  if (provider !== 'anthropic') return model
+  if (!ANTHROPIC_MODELS.includes(model as AnthropicModel)) return model
+  return MODEL_LABELS[model as AnthropicModel] ?? model
+}

package/src/ui/utils/text.ts

@@ -0,0 +1,18 @@
+/**
+ * Truncate text to a maximum number of lines, keeping the last N lines (tail).
+ * Useful for streaming content where the most recent output is most relevant.
+ */
+export function truncateLines(
+  text: string,
+  maxLines: number,
+): { text: string; truncatedCount: number } {
+  const lines = text.split('\n')
+  if (lines.length <= maxLines) {
+    return { text, truncatedCount: 0 }
+  }
+  const truncated = lines.slice(-maxLines)
+  return {
+    text: truncated.join('\n'),
+    truncatedCount: lines.length - maxLines,
+  }
+}

package/src/ui/utils/tool-format.ts

@@ -0,0 +1,40 @@
+export const TOOL_INPUT_KEYS: Record<string, string> = {
+  Glob: 'pattern',
+  Grep: 'pattern',
+  Read: 'file_path',
+  Bash: 'command',
+  LS: 'path',
+  bash: 'command',
+  readFile: 'path',
+  writeFile: 'path',
+}
+
+export function truncate(text: string, maxLen: number, mode: 'start' | 'end' = 'end'): string {
+  if (text.length <= maxLen) return text
+  if (mode === 'start') {
+    return '...' + text.slice(-(maxLen - 3))
+  }
+  return text.slice(0, maxLen - 3) + '...'
+}
+
+export function formatToolInput(name: string, input: Record<string, unknown>): string {
+  const key = TOOL_INPUT_KEYS[name] ?? Object.keys(input)[0]
+  if (!key || input[key] === undefined) {
+    if ('value' in input && input.value !== undefined) {
+      return truncate(String(input.value), 40, 'end')
+    }
+    return ''
+  }
+
+  const value = String(input[key])
+  const truncateMode = name === 'Read' ? 'start' : 'end'
+  return truncate(value, 40, truncateMode)
+}
+
+export const STATUS_CONFIG = {
+  running: { icon: '⠋', color: 'yellow' },
+  error: { icon: '✗', color: 'red' },
+  complete: { icon: '✓', color: 'green' },
+} as const
+
+export type ToolStatus = keyof typeof STATUS_CONFIG