nastech-tui 0.0.1

package/src/lib/subagentTree.ts

@@ -0,0 +1,355 @@
+import type { SubagentAggregate, SubagentNode, SubagentProgress } from '../types.js'
+
+const ROOT_KEY = '__root__'
+
+/**
+ * Reconstruct the subagent spawn tree from a flat event-ordered list.
+ *
+ * Grouping is by `parentId`; a missing `parentId` (or one pointing at an
+ * unknown subagent) is treated as a top-level spawn of the current turn.
+ * Children within a parent are sorted by `depth` then `index` — same key
+ * used in `turnController.upsertSubagent`, so render order matches spawn
+ * order regardless of network reordering of gateway events.
+ *
+ * Older gateways omit `parentId`; every subagent is then a top-level node
+ * and the tree renders flat — matching pre-observability behaviour.
+ */
+export function buildSubagentTree(items: readonly SubagentProgress[]): SubagentNode[] {
+  if (!items.length) {
+    return []
+  }
+
+  const byParent = new Map<string, SubagentProgress[]>()
+  const known = new Set<string>()
+
+  for (const item of items) {
+    known.add(item.id)
+  }
+
+  for (const item of items) {
+    const parentKey = item.parentId && known.has(item.parentId) ? item.parentId : ROOT_KEY
+    const bucket = byParent.get(parentKey) ?? []
+    bucket.push(item)
+    byParent.set(parentKey, bucket)
+  }
+
+  for (const bucket of byParent.values()) {
+    bucket.sort((a, b) => a.depth - b.depth || a.index - b.index)
+  }
+
+  const build = (item: SubagentProgress): SubagentNode => {
+    const kids = byParent.get(item.id) ?? []
+    const children = kids.map(build)
+
+    return { aggregate: aggregate(item, children), children, item }
+  }
+
+  return (byParent.get(ROOT_KEY) ?? []).map(build)
+}
+
+/**
+ * Roll up counts for a node's whole subtree.  Kept pure so the live view
+ * and the post-hoc replay can share the same renderer unchanged.
+ *
+ * `hotness` = tools per second across the subtree — a crude proxy for
+ * "how much work is happening in this branch".  Used to colour tree rails
+ * in the overlay / inline view so the eye spots the expensive branch.
+ */
+export function aggregate(item: SubagentProgress, children: readonly SubagentNode[]): SubagentAggregate {
+  let totalTools = item.toolCount ?? 0
+  let totalDuration = item.durationSeconds ?? 0
+  let descendantCount = 0
+  let activeCount = isRunning(item) ? 1 : 0
+  let maxDepthFromHere = 0
+  let inputTokens = item.inputTokens ?? 0
+  let outputTokens = item.outputTokens ?? 0
+  let costUsd = item.costUsd ?? 0
+  let filesTouched = (item.filesRead?.length ?? 0) + (item.filesWritten?.length ?? 0)
+
+  for (const child of children) {
+    totalTools += child.aggregate.totalTools
+    totalDuration += child.aggregate.totalDuration
+    descendantCount += child.aggregate.descendantCount + 1
+    activeCount += child.aggregate.activeCount
+    maxDepthFromHere = Math.max(maxDepthFromHere, child.aggregate.maxDepthFromHere + 1)
+    inputTokens += child.aggregate.inputTokens
+    outputTokens += child.aggregate.outputTokens
+    costUsd += child.aggregate.costUsd
+    filesTouched += child.aggregate.filesTouched
+  }
+
+  const hotness = totalDuration > 0 ? totalTools / totalDuration : 0
+
+  return {
+    activeCount,
+    costUsd,
+    descendantCount,
+    filesTouched,
+    hotness,
+    inputTokens,
+    maxDepthFromHere,
+    outputTokens,
+    totalDuration,
+    totalTools
+  }
+}
+
+/**
+ * Count of subagents at each depth level, indexed by depth (0 = top level).
+ * Drives the inline sparkline (`▁▃▇▅`) and the status-bar HUD.
+ */
+export function widthByDepth(tree: readonly SubagentNode[]): number[] {
+  const widths: number[] = []
+
+  const walk = (nodes: readonly SubagentNode[], depth: number) => {
+    if (!nodes.length) {
+      return
+    }
+
+    widths[depth] = (widths[depth] ?? 0) + nodes.length
+
+    for (const node of nodes) {
+      walk(node.children, depth + 1)
+    }
+  }
+
+  walk(tree, 0)
+
+  return widths
+}
+
+/**
+ * Flat totals across the full tree — feeds the summary chip header.
+ */
+export function treeTotals(tree: readonly SubagentNode[]): SubagentAggregate {
+  let totalTools = 0
+  let totalDuration = 0
+  let descendantCount = 0
+  let activeCount = 0
+  let maxDepthFromHere = 0
+  let inputTokens = 0
+  let outputTokens = 0
+  let costUsd = 0
+  let filesTouched = 0
+
+  for (const node of tree) {
+    totalTools += node.aggregate.totalTools
+    totalDuration += node.aggregate.totalDuration
+    descendantCount += node.aggregate.descendantCount + 1
+    activeCount += node.aggregate.activeCount
+    maxDepthFromHere = Math.max(maxDepthFromHere, node.aggregate.maxDepthFromHere + 1)
+    inputTokens += node.aggregate.inputTokens
+    outputTokens += node.aggregate.outputTokens
+    costUsd += node.aggregate.costUsd
+    filesTouched += node.aggregate.filesTouched
+  }
+
+  const hotness = totalDuration > 0 ? totalTools / totalDuration : 0
+
+  return {
+    activeCount,
+    costUsd,
+    descendantCount,
+    filesTouched,
+    hotness,
+    inputTokens,
+    maxDepthFromHere,
+    outputTokens,
+    totalDuration,
+    totalTools
+  }
+}
+
+/**
+ * Flatten the tree into visit order — useful for keyboard navigation and
+ * for "kill subtree" walks that fire one RPC per descendant.
+ */
+export function flattenTree(tree: readonly SubagentNode[]): SubagentNode[] {
+  const out: SubagentNode[] = []
+
+  const walk = (nodes: readonly SubagentNode[]) => {
+    for (const node of nodes) {
+      out.push(node)
+      walk(node.children)
+    }
+  }
+
+  walk(tree)
+
+  return out
+}
+
+/**
+ * Collect every descendant's id for a given node (excluding the node itself).
+ */
+export function descendantIds(node: SubagentNode): string[] {
+  const ids: string[] = []
+
+  const walk = (children: readonly SubagentNode[]) => {
+    for (const child of children) {
+      ids.push(child.item.id)
+      walk(child.children)
+    }
+  }
+
+  walk(node.children)
+
+  return ids
+}
+
+export function isRunning(item: Pick<SubagentProgress, 'status'>): boolean {
+  return item.status === 'running' || item.status === 'queued'
+}
+
+const SPARK_RAMP = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'] as const
+
+/**
+ * 8-step unicode bar sparkline from a positive-integer array.  Zeroes render
+ * as spaces so a sparse tree doesn't read as equal activity at every depth.
+ */
+export function sparkline(values: readonly number[]): string {
+  if (!values.length) {
+    return ''
+  }
+
+  const max = Math.max(...values)
+
+  if (max <= 0) {
+    return ' '.repeat(values.length)
+  }
+
+  return values
+    .map(v => {
+      if (v <= 0) {
+        return ' '
+      }
+
+      const idx = Math.min(SPARK_RAMP.length - 1, Math.max(0, Math.ceil((v / max) * (SPARK_RAMP.length - 1))))
+
+      return SPARK_RAMP[idx]
+    })
+    .join('')
+}
+
+/**
+ * Format totals into a compact one-line summary: `d2 · 7 agents · 124 tools · 2m 14s`
+ */
+export function formatSummary(totals: SubagentAggregate): string {
+  const pieces = [`d${Math.max(0, totals.maxDepthFromHere)}`]
+  pieces.push(`${totals.descendantCount} agent${totals.descendantCount === 1 ? '' : 's'}`)
+
+  if (totals.totalTools > 0) {
+    pieces.push(`${totals.totalTools} tool${totals.totalTools === 1 ? '' : 's'}`)
+  }
+
+  if (totals.totalDuration > 0) {
+    pieces.push(fmtDuration(totals.totalDuration))
+  }
+
+  const tokens = totals.inputTokens + totals.outputTokens
+
+  if (tokens > 0) {
+    pieces.push(`${fmtTokens(tokens)} tok`)
+  }
+
+  if (totals.costUsd > 0) {
+    pieces.push(fmtCost(totals.costUsd))
+  }
+
+  if (totals.activeCount > 0) {
+    pieces.push(`⚡${totals.activeCount}`)
+  }
+
+  return pieces.join(' · ')
+}
+
+/** Compact dollar amount: `$0.02`, `$1.34`, `$12.4` — never > 5 chars beyond the `$`. */
+export function fmtCost(usd: number): string {
+  if (!Number.isFinite(usd) || usd <= 0) {
+    return ''
+  }
+
+  if (usd < 0.01) {
+    return '<$0.01'
+  }
+
+  if (usd < 10) {
+    return `$${usd.toFixed(2)}`
+  }
+
+  return `$${usd.toFixed(1)}`
+}
+
+/** Compact token count: `12k`, `1.2k`, `542`. */
+export function fmtTokens(n: number): string {
+  if (!Number.isFinite(n) || n <= 0) {
+    return '0'
+  }
+
+  if (n < 1000) {
+    return String(Math.round(n))
+  }
+
+  if (n < 10_000) {
+    return `${(n / 1000).toFixed(1)}k`
+  }
+
+  return `${Math.round(n / 1000)}k`
+}
+
+/**
+ * `Ns` / `Nm` / `Nm Ss` formatter for seconds.  Shared with the agents
+ * overlay so the timeline + list + summary all speak the same dialect.
+ */
+export function fmtDuration(seconds: number): string {
+  if (seconds < 60) {
+    return `${Math.max(0, Math.round(seconds))}s`
+  }
+
+  const m = Math.floor(seconds / 60)
+  const s = Math.round(seconds - m * 60)
+
+  return s === 0 ? `${m}m` : `${m}m ${s}s`
+}
+
+/**
+ * A subagent is top-level if it has no `parentId`, or its parent isn't in
+ * the same snapshot (orphaned by a pruned mid-flight root).  Same rule
+ * `buildSubagentTree` uses — keep call sites consistent across the live
+ * view, disk label, and diff pane.
+ */
+export function topLevelSubagents(items: readonly SubagentProgress[]): SubagentProgress[] {
+  const ids = new Set(items.map(s => s.id))
+
+  return items.filter(s => !s.parentId || !ids.has(s.parentId))
+}
+
+/**
+ * Normalize a node's hotness into a palette index 0..N-1 where N = buckets.
+ * Higher hotness = "hotter" colour. Normalized against the tree's peak hotness
+ * so a uniformly slow tree still shows gradient across its busiest branches.
+ */
+export function hotnessBucket(hotness: number, peakHotness: number, buckets: number): number {
+  if (!Number.isFinite(hotness) || hotness <= 0 || peakHotness <= 0 || buckets <= 1) {
+    return 0
+  }
+
+  const ratio = Math.min(1, hotness / peakHotness)
+
+  return Math.min(buckets - 1, Math.max(0, Math.round(ratio * (buckets - 1))))
+}
+
+export function peakHotness(tree: readonly SubagentNode[]): number {
+  let peak = 0
+
+  const walk = (nodes: readonly SubagentNode[]) => {
+    for (const node of nodes) {
+      peak = Math.max(peak, node.aggregate.hotness)
+      walk(node.children)
+    }
+  }
+
+  walk(tree)
+
+  return peak
+}

package/src/lib/syntax.ts

@@ -0,0 +1,117 @@
+import type { Theme } from '../theme.js'
+
+export type Token = [string, string]
+
+interface LangSpec {
+  comment: null | string
+  keywords: Set<string>
+}
+
+const KW = (s: string) => new Set(s.split(/\s+/).filter(Boolean))
+
+const TS = KW(`
+  abstract as async await break case catch class const continue debugger default delete do else enum export extends
+  false finally for from function get if implements import in instanceof interface is let new null of package private
+  protected public readonly return set static super switch this throw true try type typeof undefined var void while
+  with yield
+`)
+
+const PY = KW(`
+  False None True and as assert async await break class continue def del elif else except finally for from global if
+  import in is lambda nonlocal not or pass raise return try while with yield
+`)
+
+const SH = KW(`
+  if then else elif fi for in do done while until case esac function return break continue local export readonly
+  declare typeset
+`)
+
+const GO = KW(`
+  break case chan const continue default defer else fallthrough for func go goto if import interface map package range
+  return select struct switch type var nil true false
+`)
+
+const RUST = KW(`
+  as async await break const continue crate dyn else enum extern false fn for if impl in let loop match mod move mut
+  pub ref return self Self static struct super trait true type unsafe use where while yield
+`)
+
+const SQL = KW(`
+  select from where and or not in is null as by group order limit offset insert into values update set delete create
+  table drop alter add column primary key foreign references join left right inner outer on
+`)
+
+const LANGS: Record<string, LangSpec> = {
+  go: { comment: '//', keywords: GO },
+  json: { comment: null, keywords: KW('true false null') },
+  py: { comment: '#', keywords: PY },
+  rust: { comment: '//', keywords: RUST },
+  sh: { comment: '#', keywords: SH },
+  sql: { comment: '--', keywords: SQL },
+  ts: { comment: '//', keywords: TS },
+  yaml: { comment: '#', keywords: KW('true false null yes no on off') }
+}
+
+const ALIAS: Record<string, string> = {
+  bash: 'sh',
+  javascript: 'ts',
+  js: 'ts',
+  jsx: 'ts',
+  python: 'py',
+  rs: 'rust',
+  shell: 'sh',
+  tsx: 'ts',
+  typescript: 'ts',
+  yml: 'yaml',
+  zsh: 'sh'
+}
+
+const resolve = (lang: string): LangSpec | null => LANGS[ALIAS[lang] ?? lang] ?? null
+
+export const isHighlightable = (lang: string): boolean => resolve(lang) !== null
+
+const TOKEN_RE = /'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"|`(?:[^`\\]|\\.)*`|\b\d+(?:\.\d+)?\b|[A-Za-z_$][\w$]*/g
+
+export function highlightLine(line: string, lang: string, t: Theme): Token[] {
+  const spec = resolve(lang)
+
+  if (!spec) {
+    return [['', line]]
+  }
+
+  if (spec.comment && line.trimStart().startsWith(spec.comment)) {
+    return [[t.color.muted, line]]
+  }
+
+  const tokens: Token[] = []
+  let last = 0
+
+  for (const m of line.matchAll(TOKEN_RE)) {
+    const start = m.index ?? 0
+
+    if (start > last) {
+      tokens.push(['', line.slice(last, start)])
+    }
+
+    const tok = m[0]
+    const ch = tok[0]!
+
+    if (ch === '"' || ch === "'" || ch === '`') {
+      tokens.push([t.color.accent, tok])
+    } else if (ch >= '0' && ch <= '9') {
+      tokens.push([t.color.text, tok])
+    } else if (spec.keywords.has(tok)) {
+      tokens.push([t.color.border, tok])
+    } else {
+      tokens.push(['', tok])
+    }
+
+    last = start + tok.length
+  }
+
+  if (last < line.length) {
+    tokens.push(['', line.slice(last)])
+  }
+
+  return tokens
+}

package/src/lib/terminalModes.ts

@@ -0,0 +1,51 @@
+import { writeSync } from 'node:fs'
+
+export const TERMINAL_MODE_RESET =
+  '\x1b[0\'z' + // DEC locator reporting
+  '\x1b[0\'{' + // selectable locator events
+  '\x1b[?2029l' + // passive mouse
+  '\x1b[?1016l' + // SGR-pixels mouse
+  '\x1b[?1015l' + // urxvt decimal mouse
+  '\x1b[?1006l' + // SGR mouse
+  '\x1b[?1005l' + // UTF-8 extended mouse
+  '\x1b[?1003l' + // any-motion mouse
+  '\x1b[?1002l' + // button-motion mouse
+  '\x1b[?1001l' + // highlight mouse
+  '\x1b[?1000l' + // click mouse
+  '\x1b[?9l' + // X10 mouse
+  '\x1b[?1004l' + // focus events
+  '\x1b[?2004l' + // bracketed paste
+  '\x1b[?1049l' + // alternate screen
+  '\x1b[<u' + // kitty keyboard
+  '\x1b[>4m' + // modifyOtherKeys
+  '\x1b[0m' + // attributes
+  '\x1b[?25h' // cursor visible
+
+type ResettableStream = Pick<NodeJS.WriteStream, 'isTTY' | 'write'> & {
+  fd?: number
+}
+
+export function resetTerminalModes(stream: ResettableStream = process.stdout): boolean {
+  if (!stream.isTTY) {
+    return false
+  }
+
+  const fd = typeof stream.fd === 'number' ? stream.fd : stream === process.stdout ? 1 : undefined
+  if (fd !== undefined) {
+    try {
+      writeSync(fd, TERMINAL_MODE_RESET)
+
+      return true
+    } catch {
+      // Fall through to stream.write for mocked or unusual TTY streams.
+    }
+  }
+
+  try {
+    stream.write(TERMINAL_MODE_RESET)
+
+    return true
+  } catch {
+    return false
+  }
+}

package/src/lib/terminalParity.ts

@@ -0,0 +1,78 @@
+import {
+  detectVSCodeLikeTerminal,
+  type FileOps,
+  isRemoteShellSession,
+  shouldPromptForTerminalSetup
+} from './terminalSetup.js'
+
+export type MacTerminalHint = {
+  key: string
+  message: string
+  tone: 'info' | 'warn'
+}
+
+export type MacTerminalContext = {
+  isAppleTerminal: boolean
+  isRemote: boolean
+  isTmux: boolean
+  vscodeLike: null | 'cursor' | 'vscode' | 'windsurf'
+}
+
+export function detectMacTerminalContext(env: NodeJS.ProcessEnv = process.env): MacTerminalContext {
+  const termProgram = env['TERM_PROGRAM'] ?? ''
+
+  return {
+    isAppleTerminal: termProgram === 'Apple_Terminal' || !!env['TERM_SESSION_ID'],
+    isRemote: isRemoteShellSession(env),
+    isTmux: !!env['TMUX'],
+    vscodeLike: detectVSCodeLikeTerminal(env)
+  }
+}
+
+export async function terminalParityHints(
+  env: NodeJS.ProcessEnv = process.env,
+  options?: { fileOps?: Partial<FileOps>; homeDir?: string }
+): Promise<MacTerminalHint[]> {
+  const ctx = detectMacTerminalContext(env)
+  const hints: MacTerminalHint[] = []
+
+  if (
+    ctx.vscodeLike &&
+    (await shouldPromptForTerminalSetup({ env, fileOps: options?.fileOps, homeDir: options?.homeDir }))
+  ) {
+    hints.push({
+      key: 'ide-setup',
+      tone: 'info',
+      message: `Detected ${ctx.vscodeLike} terminal · run /terminal-setup for best Cmd+Enter / undo parity`
+    })
+  }
+
+  if (ctx.isAppleTerminal) {
+    hints.push({
+      key: 'apple-terminal',
+      tone: 'warn',
+      message:
+        'Apple Terminal detected · use /paste for image-only clipboard fallback, and try Ctrl+A / Ctrl+E / Ctrl+U if Cmd+←/→/⌫ gets rewritten'
+    })
+  }
+
+  if (ctx.isTmux) {
+    hints.push({
+      key: 'tmux',
+      tone: 'warn',
+      message:
+        'tmux detected · clipboard copy/paste uses passthrough when available; allow-passthrough improves OSC52 reliability'
+    })
+  }
+
+  if (ctx.isRemote) {
+    hints.push({
+      key: 'remote',
+      tone: 'warn',
+      message:
+        'SSH session detected · text clipboard can bridge via OSC52, but image clipboard and local screenshot paths still depend on the machine running NasTech'
+    })
+  }
+
+  return hints
+}