typeclaw 0.1.0

package/src/tui/format.ts

@@ -0,0 +1,317 @@
+import { colors } from './theme'
+
+const ARGS_PREVIEW_MAX = 200
+const RESULT_PREVIEW_MAX = 400
+
+export function formatToolStart(name: string, args: unknown): string {
+  const head = `${colors.cyan('●')} ${colors.bold(name)}`
+  const preview = previewArgs(name, args)
+  return preview === null ? head : `${head} ${colors.dim(preview)}`
+}
+
+export function formatToolEnd(name: string, error: boolean, result: unknown, durationMs: number): string {
+  const glyph = error ? colors.red('✗') : colors.green('✓')
+  const dur = colors.gray(formatDuration(durationMs))
+  const head = `${glyph} ${colors.bold(name)} ${dur}`
+  const preview = previewResult(name, error, result)
+  return preview === null ? head : `${head}\n${preview}`
+}
+
+export function formatUserPromptHistory(text: string): string {
+  return stripHiddenBlocks(text)
+    .split('\n')
+    .map((line, idx) => `${colors.dim(idx === 0 ? '>' : '.')} ${line}`)
+    .join('\n')
+}
+
+function stripHiddenBlocks(text: string): string {
+  return text.replace(/<hatching>[\s\S]*?<\/hatching>\s*/g, '').trimStart()
+}
+
+export function formatQueuePanel(items: ReadonlyArray<{ text: string }>): string {
+  return items.map((item) => `${colors.dim('[QUEUED]')} ${firstLine(item.text)}`).join('\n')
+}
+
+function firstLine(text: string): string {
+  const idx = text.indexOf('\n')
+  if (idx === -1) return text
+  const head = text.slice(0, idx)
+  const remaining = text.length - idx
+  return `${head} ${colors.dim(`(+${remaining} chars)`)}`
+}
+
+// Tool-specific argument summaries. Each humanizer collapses the typical
+// `{path, pattern, command, …}` parameter object into a single line that
+// reads naturally next to the tool name. Returning null means "I don't
+// recognize this shape, fall back to the generic compact JSON".
+type ArgRecord = Record<string, unknown>
+
+function humanizeArgs(name: string, args: unknown): string | null {
+  if (!isObject(args)) return null
+  switch (name) {
+    case 'read':
+      return humanizeReadArgs(args)
+    case 'bash':
+      return humanizeBashArgs(args)
+    case 'edit':
+      return humanizeEditArgs(args)
+    case 'write':
+      return humanizeWriteArgs(args)
+    case 'grep':
+      return humanizeGrepArgs(args)
+    case 'find':
+      return humanizeFindArgs(args)
+    case 'ls':
+      return humanizeLsArgs(args)
+    case 'websearch':
+      return humanizeWebsearchArgs(args)
+    case 'webfetch':
+      return humanizeWebfetchArgs(args)
+    default:
+      return null
+  }
+}
+
+function humanizeReadArgs(args: ArgRecord): string | null {
+  const path = asString(args.path)
+  if (path === null) return null
+  const offset = asNumber(args.offset)
+  const limit = asNumber(args.limit)
+  if (offset !== null && limit !== null) return `${path} (lines ${offset}-${offset + limit - 1})`
+  if (offset !== null) return `${path} (from line ${offset})`
+  if (limit !== null) return `${path} (first ${limit} lines)`
+  return path
+}
+
+function humanizeBashArgs(args: ArgRecord): string | null {
+  const command = asString(args.command)
+  if (command === null) return null
+  return command.replace(/\s+/g, ' ').trim()
+}
+
+function humanizeEditArgs(args: ArgRecord): string | null {
+  const path = asString(args.path)
+  if (path === null) return null
+  const edits = Array.isArray(args.edits) ? args.edits.length : 0
+  return edits > 0 ? `${path} (${edits} edit${edits === 1 ? '' : 's'})` : path
+}
+
+function humanizeWriteArgs(args: ArgRecord): string | null {
+  const path = asString(args.path)
+  if (path === null) return null
+  const content = asString(args.content)
+  if (content === null) return path
+  const bytes = Buffer.byteLength(content, 'utf-8')
+  return `${path} (${formatBytes(bytes)})`
+}
+
+function humanizeGrepArgs(args: ArgRecord): string | null {
+  const pattern = asString(args.pattern)
+  if (pattern === null) return null
+  const where = asString(args.path) ?? asString(args.glob)
+  return where ? `"${pattern}" in ${where}` : `"${pattern}"`
+}
+
+function humanizeFindArgs(args: ArgRecord): string | null {
+  const pattern = asString(args.pattern)
+  if (pattern === null) return null
+  const where = asString(args.path)
+  return where ? `${pattern} in ${where}` : pattern
+}
+
+function humanizeLsArgs(args: ArgRecord): string | null {
+  return asString(args.path) ?? '.'
+}
+
+function humanizeWebsearchArgs(args: ArgRecord): string | null {
+  const query = asString(args.query)
+  if (query === null) return null
+  const source = asString(args.source)
+  return source && source !== 'web' ? `"${query}" (${source})` : `"${query}"`
+}
+
+function humanizeWebfetchArgs(args: ArgRecord): string | null {
+  return asString(args.url)
+}
+
+// Tool-specific result enrichments. Most tools already embed a human-readable
+// summary in `content[].text`, so the default path simply extracts that. The
+// exceptions: `edit` benefits from showing the diff, `bash` likes a footer
+// with truncation/full-output info, image reads collapse to `[image]`.
+function humanizeResult(name: string, result: unknown): string | null {
+  if (!isObject(result)) return null
+  const enriched = enrichResult(name, result)
+  if (enriched !== null) return enriched
+  return extractContentText(result)
+}
+
+function enrichResult(name: string, result: ArgRecord): string | null {
+  switch (name) {
+    case 'edit':
+      return enrichEditResult(result)
+    case 'bash':
+      return enrichBashResult(result)
+    case 'read':
+      return enrichReadResult(result)
+    case 'websearch':
+      return enrichWebsearchResult(result)
+    default:
+      return null
+  }
+}
+
+function enrichEditResult(result: ArgRecord): string | null {
+  const details = isObject(result.details) ? result.details : null
+  const diff = details ? asString(details.diff) : null
+  if (diff !== null) return diff
+  return null
+}
+
+function enrichBashResult(result: ArgRecord): string | null {
+  const text = extractContentText(result)
+  if (text === null) return null
+  const details = isObject(result.details) ? result.details : null
+  const fullOutput = details ? asString(details.fullOutputPath) : null
+  if (fullOutput === null) return text
+  return `${text}\n\nFull output saved to: ${fullOutput}`
+}
+
+function enrichReadResult(result: ArgRecord): string | null {
+  const content = Array.isArray(result.content) ? result.content : null
+  if (content === null) return null
+  const hasImage = content.some((part) => isObject(part) && part.type === 'image')
+  if (!hasImage) return null
+  const mime = content
+    .map((part) => (isObject(part) && part.type === 'image' ? asString(part.mimeType) : null))
+    .find((m) => m !== null)
+  return mime ? `[image: ${mime}]` : '[image]'
+}
+
+function enrichWebsearchResult(result: ArgRecord): string | null {
+  const details = isObject(result.details) ? result.details : null
+  if (details === null) return null
+  const results = Array.isArray(details.results) ? details.results : null
+  if (results === null || results.length === 0) {
+    return extractContentText(result)
+  }
+  const query = asString(details.query) ?? ''
+  const source = asString(details.source) ?? ''
+  const header = query ? `${results.length} result${results.length === 1 ? '' : 's'} for "${query}" (${source})` : null
+  const lines = results
+    .map((entry, i) => formatWebsearchEntry(entry, i + 1))
+    .filter((line): line is string => line !== null)
+  if (lines.length === 0) return extractContentText(result)
+  return header === null ? lines.join('\n') : `${header}\n${lines.join('\n')}`
+}
+
+function formatWebsearchEntry(entry: unknown, index: number): string | null {
+  if (!isObject(entry)) return null
+  const title = asString(entry.title)
+  const url = asString(entry.url)
+  if (title === null || url === null) return null
+  return `${index}. ${title} — ${url}`
+}
+
+// AI-SDK style results carry a `content` array of `{type, text|data, …}` parts.
+// We join all `text` parts with blank lines between them and replace any
+// non-text parts with a placeholder so the user sees that something was there.
+function extractContentText(result: ArgRecord): string | null {
+  const content = result.content
+  if (!Array.isArray(content) || content.length === 0) return null
+  const parts: string[] = []
+  for (const part of content) {
+    if (!isObject(part)) continue
+    if (part.type === 'text') {
+      const text = asString(part.text)
+      if (text !== null) parts.push(text)
+      continue
+    }
+    if (part.type === 'image') {
+      const mime = asString(part.mimeType)
+      parts.push(mime ? `[image: ${mime}]` : '[image]')
+      continue
+    }
+    parts.push(`[${asString(part.type) ?? 'attachment'}]`)
+  }
+  if (parts.length === 0) return null
+  return parts.join('\n\n')
+}
+
+function previewArgs(name: string, args: unknown): string | null {
+  if (args === undefined || args === null) return null
+  if (typeof args === 'object' && Object.keys(args as object).length === 0) return null
+  const humanized = humanizeArgs(name, args)
+  const raw = humanized ?? toCompactString(args)
+  return truncate(raw, ARGS_PREVIEW_MAX)
+}
+
+function previewResult(name: string, error: boolean, result: unknown): string | null {
+  if (result === undefined || result === null) return null
+  if (typeof result === 'string') return formatPreviewBlock(result, error)
+  const humanized = humanizeResult(name, result)
+  const raw = humanized ?? toReadableString(result)
+  return raw.length === 0 ? null : formatPreviewBlock(raw, error)
+}
+
+function formatPreviewBlock(raw: string, error: boolean): string {
+  const truncated = truncate(raw, RESULT_PREVIEW_MAX)
+  const colorize = error ? colors.red : colors.gray
+  return truncated
+    .split('\n')
+    .map((line) => `  ${colorize(line)}`)
+    .join('\n')
+}
+
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`
+  const seconds = ms / 1000
+  if (seconds < 60) return `${seconds.toFixed(seconds < 10 ? 2 : 1)}s`
+  const minutes = Math.floor(seconds / 60)
+  const remaining = Math.round(seconds - minutes * 60)
+  return `${minutes}m${remaining}s`
+}
+
+function toCompactString(value: unknown): string {
+  if (typeof value === 'string') return value
+  try {
+    return JSON.stringify(value)
+  } catch {
+    return String(value)
+  }
+}
+
+function toReadableString(value: unknown): string {
+  if (typeof value === 'string') return value
+  try {
+    return JSON.stringify(value, null, 2)
+  } catch {
+    return String(value)
+  }
+}
+
+function truncate(text: string, max: number): string {
+  if (text.length <= max) return text
+  const cut = text.slice(0, max)
+  const remaining = text.length - max
+  return `${cut}… (+${remaining} chars)`
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`
+  const kb = bytes / 1024
+  if (kb < 1024) return `${kb < 10 ? kb.toFixed(1) : Math.round(kb)}KB`
+  const mb = kb / 1024
+  return `${mb < 10 ? mb.toFixed(1) : Math.round(mb)}MB`
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function asString(value: unknown): string | null {
+  return typeof value === 'string' ? value : null
+}
+
+function asNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null
+}

package/src/tui/index.ts

@@ -0,0 +1,225 @@
+import { Editor, Key, Markdown, matchesKey, ProcessTerminal, type Terminal, Text, TUI } from '@mariozechner/pi-tui'
+
+import { createClient as createClientDefault, type Client } from './client'
+import { formatQueuePanel, formatToolEnd, formatToolStart, formatUserPromptHistory } from './format'
+import { colors, editorTheme, markdownTheme } from './theme'
+
+export type ClientFactory = (url: string) => Promise<Client>
+export type TerminalFactory = () => Terminal
+
+export type TuiOptions = {
+  url: string
+  initialPrompt?: string
+  createClient?: ClientFactory
+  createTerminal?: TerminalFactory
+  exit?: (code: number) => void
+}
+
+export function createTui({
+  url,
+  initialPrompt,
+  createClient = createClientDefault,
+  createTerminal = () => new ProcessTerminal(),
+  exit = process.exit.bind(process),
+}: TuiOptions) {
+  async function run(): Promise<void> {
+    const terminal = createTerminal()
+    const tui = new TUI(terminal)
+
+    const status = new Text(colors.dim(`connecting to ${url}...`), 0, 0)
+    tui.addChild(status)
+    tui.start()
+    tui.requestRender()
+
+    const client = await createClient(url).catch((err) => {
+      status.setText(colors.red(`connection error: ${err instanceof Error ? err.message : String(err)}`))
+      tui.requestRender()
+      tui.stop()
+      exit(1)
+      throw err
+    })
+
+    const sessionId = await new Promise<string>((resolve) => {
+      let off: (() => void) | undefined
+      off = client.onMessage((msg) => {
+        if (msg.type === 'connected') {
+          off?.()
+          resolve(msg.sessionId)
+        }
+      })
+    })
+    status.setText(colors.dim(`session: ${sessionId}`))
+    tui.requestRender()
+
+    const editor = new Editor(tui, editorTheme, { paddingX: 0 })
+    let replyInFlight = false
+    let onReplyDone: (() => void) | null = null
+    let currentAssistant: Markdown | null = null
+    let currentAssistantText = ''
+    let queuePanel: Text | null = null
+
+    // Pi-tui's Container.addChild appends to the end of the children array.
+    // The editor must remain the LAST child at all times so it stays pinned
+    // to the bottom of the viewport, with chat history scrolling above it.
+    // The queue panel, when present, sits immediately ABOVE the editor (so
+    // the layout is [...history, queuePanel?, editor]). Any new history entry
+    // is inserted by stripping the queue panel + editor from the tail,
+    // appending the entry, then re-appending them in order.
+    const appendHistory = (component: Text | Markdown) => {
+      if (queuePanel) tui.removeChild(queuePanel)
+      tui.removeChild(editor)
+      tui.addChild(component)
+      if (queuePanel) tui.addChild(queuePanel)
+      tui.addChild(editor)
+    }
+
+    const updateQueuePanel = (pending: ReadonlyArray<{ id: string; text: string; ts: number }>) => {
+      if (pending.length === 0) {
+        if (queuePanel) {
+          tui.removeChild(queuePanel)
+          queuePanel = null
+          tui.requestRender()
+        }
+        return
+      }
+      const text = formatQueuePanel(pending)
+      if (queuePanel) {
+        queuePanel.setText(text)
+      } else {
+        queuePanel = new Text(text, 0, 0)
+        tui.removeChild(editor)
+        tui.addChild(queuePanel)
+        tui.addChild(editor)
+      }
+      tui.requestRender()
+    }
+
+    // Reset between text segments so a new Markdown block is created after
+    // any non-text event (tool calls). Otherwise text_delta after a tool call
+    // would append to the previous Markdown and visually push the tool lines
+    // down on every chunk.
+    const sealAssistantBlock = () => {
+      currentAssistant = null
+      currentAssistantText = ''
+    }
+
+    const finishAssistantTurn = () => {
+      sealAssistantBlock()
+      replyInFlight = false
+      onReplyDone?.()
+      onReplyDone = null
+    }
+
+    const ensureAssistantBlock = (): Markdown => {
+      if (currentAssistant) return currentAssistant
+      const md = new Markdown('', 0, 0, markdownTheme)
+      currentAssistant = md
+      currentAssistantText = ''
+      appendHistory(md)
+      return md
+    }
+
+    client.onMessage((msg) => {
+      switch (msg.type) {
+        case 'prompt_started': {
+          appendHistory(new Text(formatUserPromptHistory(msg.text), 0, 0))
+          tui.requestRender()
+          break
+        }
+        case 'text_delta': {
+          const block = ensureAssistantBlock()
+          currentAssistantText += msg.delta
+          block.setText(currentAssistantText)
+          tui.requestRender()
+          break
+        }
+        case 'tool_start': {
+          sealAssistantBlock()
+          appendHistory(new Text(formatToolStart(msg.name, msg.args), 0, 0))
+          tui.requestRender()
+          break
+        }
+        case 'tool_end': {
+          sealAssistantBlock()
+          appendHistory(new Text(formatToolEnd(msg.name, msg.error, msg.result, msg.durationMs), 0, 0))
+          tui.requestRender()
+          break
+        }
+        case 'done': {
+          finishAssistantTurn()
+          tui.requestRender()
+          break
+        }
+        case 'error': {
+          appendHistory(new Text(colors.red(`error: ${msg.message}`), 0, 0))
+          finishAssistantTurn()
+          tui.requestRender()
+          break
+        }
+        case 'queue_state': {
+          updateQueuePanel(msg.pending)
+          break
+        }
+      }
+    })
+
+    const closed = new Promise<void>((resolve) => {
+      client.onClose(() => {
+        appendHistory(new Text(colors.dim('disconnected'), 0, 0))
+        tui.requestRender()
+        resolve()
+      })
+    })
+
+    function send(text: string): Promise<void> {
+      replyInFlight = true
+      client.send({ type: 'prompt', text })
+      return new Promise<void>((resolve) => {
+        onReplyDone = resolve
+      })
+    }
+
+    // Esc aborts an in-flight reply. The Editor does not bind Esc, so a
+    // top-level input listener can intercept it without fighting the editor.
+    tui.addInputListener((data) => {
+      if (matchesKey(data, Key.escape) && replyInFlight) {
+        client.send({ type: 'abort' })
+        return { consume: true }
+      }
+      return undefined
+    })
+
+    // Ctrl+C exits cleanly. In raw mode the kernel does NOT generate SIGINT,
+    // so we must intercept the \x03 byte ourselves. The Editor would otherwise
+    // swallow it. tui.stop() restores raw-mode/cursor/echo before we exit.
+    tui.addInputListener((data) => {
+      if (matchesKey(data, Key.ctrl('c'))) {
+        tui.stop()
+        client.close()
+        exit(0)
+        return { consume: true }
+      }
+      return undefined
+    })
+
+    editor.onSubmit = (text) => {
+      if (text.trim().length === 0) return
+      editor.setText('')
+      editor.addToHistory(text)
+      tui.requestRender()
+      void send(text)
+    }
+    tui.addChild(editor)
+    tui.setFocus(editor)
+    tui.requestRender()
+
+    if (initialPrompt) {
+      await send(initialPrompt)
+    }
+
+    await closed
+    tui.stop()
+  }
+
+  return { run }
+}

package/src/tui/theme.ts

@@ -0,0 +1,41 @@
+import type { EditorTheme, MarkdownTheme } from '@mariozechner/pi-tui'
+
+const wrap = (code: string) => (text: string) => `\x1b[${code}m${text}\x1b[0m`
+
+const dim = wrap('2')
+const bold = wrap('1')
+const red = wrap('31')
+const green = wrap('32')
+const yellow = wrap('33')
+const cyan = wrap('36')
+const gray = wrap('90')
+
+export const colors = { dim, bold, red, green, yellow, cyan, gray }
+
+export const editorTheme: EditorTheme = {
+  borderColor: dim,
+  selectList: {
+    selectedPrefix: cyan,
+    selectedText: bold,
+    description: dim,
+    scrollInfo: dim,
+    noMatch: dim,
+  },
+}
+
+export const markdownTheme: MarkdownTheme = {
+  heading: bold,
+  link: cyan,
+  linkUrl: (text) => dim(`(${text})`),
+  code: yellow,
+  codeBlock: yellow,
+  codeBlockBorder: dim,
+  quote: dim,
+  quoteBorder: dim,
+  hr: dim,
+  listBullet: cyan,
+  bold,
+  italic: (text) => `\x1b[3m${text}\x1b[23m`,
+  strikethrough: (text) => `\x1b[9m${text}\x1b[29m`,
+  underline: (text) => `\x1b[4m${text}\x1b[24m`,
+}