nastech-tui 0.0.1

package/src/lib/memory.test.ts

@@ -0,0 +1,155 @@
+import { mkdtempSync, readdirSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { performHeapDump } from './memory.js'
+
+const ENV_KEYS = ['NASTECH_AUTO_HEAPDUMP', 'NASTECH_HEAPDUMP_DIR', 'NASTECH_HEAPDUMP_MAX_BYTES'] as const
+
+describe('performHeapDump auto opt-in gate (#21767)', () => {
+  let saved: Record<string, string | undefined>
+  let dir: string
+
+  beforeEach(() => {
+    saved = {}
+
+    for (const k of ENV_KEYS) {
+      saved[k] = process.env[k]
+      delete process.env[k]
+    }
+
+    dir = mkdtempSync(join(tmpdir(), 'nastech-heapdump-test-'))
+    process.env.NASTECH_HEAPDUMP_DIR = dir
+  })
+
+  afterEach(() => {
+    for (const k of ENV_KEYS) {
+      if (saved[k] === undefined) {
+        delete process.env[k]
+      } else {
+        process.env[k] = saved[k]
+      }
+    }
+
+    rmSync(dir, { force: true, recursive: true })
+  })
+
+  it('writes diagnostics only for auto-high without NASTECH_AUTO_HEAPDUMP', async () => {
+    const result = await performHeapDump('auto-high')
+
+    expect(result.success).toBe(true)
+    expect(result.suppressed).toBe(true)
+    expect(result.diagPath).toBeDefined()
+    expect(result.heapPath).toBeUndefined()
+
+    const files = readdirSync(dir)
+    expect(files.some(f => f.endsWith('.diagnostics.json'))).toBe(true)
+    expect(files.some(f => f.endsWith('.heapsnapshot'))).toBe(false)
+  })
+
+  it('writes diagnostics only for auto-critical without NASTECH_AUTO_HEAPDUMP', async () => {
+    const result = await performHeapDump('auto-critical')
+
+    expect(result.success).toBe(true)
+    expect(result.suppressed).toBe(true)
+    expect(result.heapPath).toBeUndefined()
+
+    const files = readdirSync(dir)
+    expect(files.some(f => f.endsWith('.heapsnapshot'))).toBe(false)
+  })
+
+  it('writes both diagnostics and snapshot for auto-high when NASTECH_AUTO_HEAPDUMP=1', async () => {
+    process.env.NASTECH_AUTO_HEAPDUMP = '1'
+
+    const result = await performHeapDump('auto-high')
+
+    expect(result.success).toBe(true)
+    expect(result.suppressed).toBeUndefined()
+    expect(result.diagPath).toBeDefined()
+    expect(result.heapPath).toBeDefined()
+
+    const files = readdirSync(dir)
+    expect(files.some(f => f.endsWith('.heapsnapshot'))).toBe(true)
+  })
+
+  it('accepts truthy spellings (true|yes|on, case-insensitive) as opt-in', async () => {
+    for (const value of ['true', 'YES', 'On']) {
+      process.env.NASTECH_AUTO_HEAPDUMP = value
+      const result = await performHeapDump('auto-high')
+
+      expect(result.success).toBe(true)
+      expect(result.heapPath).toBeDefined()
+    }
+  })
+
+  it('treats other values (0, off, garbage) as opt-out for auto triggers', async () => {
+    for (const value of ['0', 'off', 'nope']) {
+      process.env.NASTECH_AUTO_HEAPDUMP = value
+      const result = await performHeapDump('auto-high')
+
+      expect(result.success).toBe(true)
+      expect(result.suppressed).toBe(true)
+      expect(result.heapPath).toBeUndefined()
+    }
+  })
+
+  it('writes both for manual triggers regardless of NASTECH_AUTO_HEAPDUMP', async () => {
+    const result = await performHeapDump('manual')
+
+    expect(result.success).toBe(true)
+    expect(result.suppressed).toBeUndefined()
+    expect(result.heapPath).toBeDefined()
+
+    const files = readdirSync(dir)
+    expect(files.some(f => f.endsWith('.heapsnapshot'))).toBe(true)
+  })
+})
+
+describe('heapdump retention guard (#21767)', () => {
+  let savedDir: string | undefined
+  let savedMax: string | undefined
+  let dir: string
+
+  beforeEach(() => {
+    savedDir = process.env.NASTECH_HEAPDUMP_DIR
+    savedMax = process.env.NASTECH_HEAPDUMP_MAX_BYTES
+    delete process.env.NASTECH_AUTO_HEAPDUMP
+    dir = mkdtempSync(join(tmpdir(), 'nastech-heapdump-prune-'))
+    process.env.NASTECH_HEAPDUMP_DIR = dir
+  })
+
+  afterEach(() => {
+    if (savedDir === undefined) {delete process.env.NASTECH_HEAPDUMP_DIR}
+    else {process.env.NASTECH_HEAPDUMP_DIR = savedDir}
+
+    if (savedMax === undefined) {delete process.env.NASTECH_HEAPDUMP_MAX_BYTES}
+    else {process.env.NASTECH_HEAPDUMP_MAX_BYTES = savedMax}
+
+    rmSync(dir, { force: true, recursive: true })
+  })
+
+  it('evicts oldest files when total bytes exceed the cap, retaining the newest', async () => {
+    const blob = 'x'.repeat(1024)
+    const now = Date.now()
+
+    for (let i = 0; i < 4; i++) {
+      const p = join(dir, `old-${i}.heapsnapshot`)
+      writeFileSync(p, blob)
+      const t = (now - (4 - i) * 60_000) / 1000
+      utimesSync(p, t, t)
+    }
+
+    process.env.NASTECH_HEAPDUMP_MAX_BYTES = String(2 * 1024)
+
+    const result = await performHeapDump('auto-high')
+    expect(result.success).toBe(true)
+
+    const remaining = readdirSync(dir)
+    const totalBytes = remaining.reduce((acc, f) => acc + statSync(join(dir, f)).size, 0)
+    expect(totalBytes <= 2 * 1024 || remaining.length === 1).toBe(true)
+    expect(remaining.length).toBeLessThan(5)
+    expect(remaining.some(f => f.endsWith('.diagnostics.json'))).toBe(true)
+  })
+})

package/src/lib/memory.ts

@@ -0,0 +1,188 @@
+import { createWriteStream } from 'node:fs'
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pipeline } from 'node:stream/promises'
+import { getHeapSnapshot, getHeapSpaceStatistics, getHeapStatistics } from 'node:v8'
+
+export type MemoryTrigger = 'auto-critical' | 'auto-high' | 'manual'
+
+export interface MemoryDiagnostics {
+  activeHandles: number
+  activeRequests: number
+  analysis: {
+    potentialLeaks: string[]
+    recommendation: string
+  }
+  memoryGrowthRate: {
+    bytesPerSecond: number
+    mbPerHour: number
+  }
+  memoryUsage: {
+    arrayBuffers: number
+    external: number
+    heapTotal: number
+    heapUsed: number
+    rss: number
+  }
+  nodeVersion: string
+  openFileDescriptors?: number
+  platform: string
+  resourceUsage: {
+    maxRSS: number
+    systemCPUTime: number
+    userCPUTime: number
+  }
+  smapsRollup?: string
+  timestamp: string
+  trigger: MemoryTrigger
+  uptimeSeconds: number
+  v8HeapSpaces?: { available: number; name: string; size: number; used: number }[]
+  v8HeapStats: {
+    detachedContexts: number
+    heapSizeLimit: number
+    mallocedMemory: number
+    nativeContexts: number
+    peakMallocedMemory: number
+  }
+}
+
+export interface HeapDumpResult {
+  diagPath?: string
+  error?: string
+  heapPath?: string
+  success: boolean
+  suppressed?: boolean
+}
+
+export async function captureMemoryDiagnostics(trigger: MemoryTrigger): Promise<MemoryDiagnostics> {
+  const usage = process.memoryUsage()
+  const heapStats = getHeapStatistics()
+  const resourceUsage = process.resourceUsage()
+  const uptimeSeconds = process.uptime()
+
+  // Not available on Bun / older Node.
+  let heapSpaces: ReturnType<typeof getHeapSpaceStatistics> | undefined
+
+  try {
+    heapSpaces = getHeapSpaceStatistics()
+  } catch {
+    /* noop */
+  }
+
+  const internals = process as unknown as {
+    _getActiveHandles: () => unknown[]
+    _getActiveRequests: () => unknown[]
+  }
+
+  const activeHandles = internals._getActiveHandles().length
+  const activeRequests = internals._getActiveRequests().length
+  const openFileDescriptors = await swallow(async () => (await readdir('/proc/self/fd')).length)
+  const smapsRollup = await swallow(() => readFile('/proc/self/smaps_rollup', 'utf8'))
+
+  const nativeMemory = usage.rss - usage.heapUsed
+  // Real growth rate since STARTED_AT (captured at module load) — NOT a lifetime
+  // average of rss/uptime, which would report phantom "growth" for a stable process.
+  const elapsed = Math.max(0, uptimeSeconds - STARTED_AT.uptime)
+  const bytesPerSecond = elapsed > 0 ? (usage.rss - STARTED_AT.rss) / elapsed : 0
+  const mbPerHour = (bytesPerSecond * 3600) / (1024 * 1024)
+
+  const potentialLeaks = [
+    heapStats.number_of_detached_contexts > 0 &&
+      `${heapStats.number_of_detached_contexts} detached context(s) — possible component/closure leak`,
+    activeHandles > 100 && `${activeHandles} active handles — possible timer/socket leak`,
+    nativeMemory > usage.heapUsed && 'Native memory > heap — leak may be in native addons',
+    mbPerHour > 100 && `High memory growth rate: ${mbPerHour.toFixed(1)} MB/hour`,
+    openFileDescriptors && openFileDescriptors > 500 && `${openFileDescriptors} open FDs — possible file/socket leak`
+  ].filter((s): s is string => typeof s === 'string')
+
+  return {
+    activeHandles,
+    activeRequests,
+    analysis: {
+      potentialLeaks,
+      recommendation: potentialLeaks.length
+        ? `WARNING: ${potentialLeaks.length} potential leak indicator(s). See potentialLeaks.`
+        : 'No obvious leak indicators. Inspect heap snapshot for retained objects.'
+    },
+    memoryGrowthRate: { bytesPerSecond, mbPerHour },
+    memoryUsage: {
+      arrayBuffers: usage.arrayBuffers,
+      external: usage.external,
+      heapTotal: usage.heapTotal,
+      heapUsed: usage.heapUsed,
+      rss: usage.rss
+    },
+    nodeVersion: process.version,
+    openFileDescriptors,
+    platform: process.platform,
+    resourceUsage: {
+      maxRSS: resourceUsage.maxRSS * 1024,
+      systemCPUTime: resourceUsage.systemCPUTime,
+      userCPUTime: resourceUsage.userCPUTime
+    },
+    smapsRollup,
+    timestamp: new Date().toISOString(),
+    trigger,
+    uptimeSeconds,
+    v8HeapSpaces: heapSpaces?.map(s => ({
+      available: s.space_available_size,
+      name: s.space_name,
+      size: s.space_size,
+      used: s.space_used_size
+    })),
+    v8HeapStats: {
+      detachedContexts: heapStats.number_of_detached_contexts,
+      heapSizeLimit: heapStats.heap_size_limit,
+      mallocedMemory: heapStats.malloced_memory,
+      nativeContexts: heapStats.number_of_native_contexts,
+      peakMallocedMemory: heapStats.peak_malloced_memory
+    }
+  }
+}
+
+export async function performHeapDump(trigger: MemoryTrigger = 'manual'): Promise<HeapDumpResult> {
+  try {
+    // Diagnostics first — heap-snapshot serialization can crash on very large
+    // heaps, and the JSON sidecar is the most actionable artifact if so.
+    const diagnostics = await captureMemoryDiagnostics(trigger)
+    const dir = process.env.NASTECH_HEAPDUMP_DIR?.trim() || join(homedir() || tmpdir(), '.nastech', 'heapdumps')
+
+    await mkdir(dir, { recursive: true })
+
+    const base = `nastech-${new Date().toISOString().replace(/[:.]/g, '-')}-${process.pid}-${trigger}`
+    const heapPath = join(dir, `${base}.heapsnapshot`)
+    const diagPath = join(dir, `${base}.diagnostics.json`)
+
+    await writeFile(diagPath, JSON.stringify(diagnostics, null, 2), { mode: 0o600 })
+    await pipeline(getHeapSnapshot(), createWriteStream(heapPath, { mode: 0o600 }))
+
+    return { diagPath, heapPath, success: true }
+  } catch (e) {
+    return { error: e instanceof Error ? e.message : String(e), success: false }
+  }
+}
+
+export function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes <= 0) {
+    return '0B'
+  }
+
+  const exp = Math.min(UNITS.length - 1, Math.floor(Math.log10(bytes) / 3))
+  const value = bytes / 1024 ** exp
+
+  return `${value >= 100 ? value.toFixed(0) : value.toFixed(1)}${UNITS[exp]}`
+}
+
+const UNITS = ['B', 'KB', 'MB', 'GB', 'TB']
+
+const STARTED_AT = { rss: process.memoryUsage().rss, uptime: process.uptime() }
+
+// Returns undefined when the probe isn't available (non-Linux paths, sandboxed FS).
+const swallow = async <T>(fn: () => Promise<T>): Promise<T | undefined> => {
+  try {
+    return await fn()
+  } catch {
+    return undefined
+  }
+}

package/src/lib/memoryMonitor.ts

@@ -0,0 +1,109 @@
+import { type HeapDumpResult, performHeapDump } from './memory.js'
+
+export type MemoryLevel = 'critical' | 'high' | 'normal'
+
+export interface MemorySnapshot {
+  heapUsed: number
+  level: MemoryLevel
+  rss: number
+}
+
+export interface MemoryMonitorOptions {
+  criticalBytes?: number
+  highBytes?: number
+  intervalMs?: number
+  onCritical?: (snap: MemorySnapshot, dump: HeapDumpResult | null) => void
+  onHigh?: (snap: MemorySnapshot, dump: HeapDumpResult | null) => void
+}
+
+const GB = 1024 ** 3
+
+// Deferred @nastech/ink import: loading `@nastechai/ink` at module top-level
+// pulls the full ~414KB Ink bundle (React, renderer, components, hooks) onto
+// the critical path before the Python gateway can even be spawned. That
+// serialised roughly 150ms of Node work in front of gw.start() on every
+// cold `nastech --tui` launch.
+//
+// evictInkCaches only runs inside `tick()`, which fires on a 10s timer and
+// only when heap pressure crosses the high-water mark — by then Ink has
+// long since been loaded by the app entry. This dynamic import is a no-op
+// on the hot path (module is already in the ESM cache); when a startup
+// spike somehow trips the threshold before the app registers its own Ink
+// import, we pay the load cost exactly once, inside the tick that needs it.
+let _evictInkCaches: ((level: 'all' | 'half') => unknown) | null = null
+let _evictInkCachesPromise: Promise<(level: 'all' | 'half') => unknown> | null = null
+
+async function _ensureEvictInkCaches(): Promise<(level: 'all' | 'half') => unknown> {
+  if (_evictInkCaches) {
+    return _evictInkCaches
+  }
+
+  _evictInkCachesPromise ??= import('@nastechai/ink')
+    .then(mod => {
+      _evictInkCaches = mod.evictInkCaches as (level: 'all' | 'half') => unknown
+
+      return _evictInkCaches
+    })
+    .catch(err => {
+      _evictInkCachesPromise = null
+      throw err
+    })
+
+  return _evictInkCachesPromise
+}
+
+export function startMemoryMonitor({
+  criticalBytes = 2.5 * GB,
+  highBytes = 1.5 * GB,
+  intervalMs = 10_000,
+  onCritical,
+  onHigh
+}: MemoryMonitorOptions = {}): () => void {
+  const dumped = new Set<Exclude<MemoryLevel, 'normal'>>()
+  const inFlight = new Set<Exclude<MemoryLevel, 'normal'>>()
+
+  const tick = async () => {
+    const { heapUsed, rss } = process.memoryUsage()
+    const level: MemoryLevel = heapUsed >= criticalBytes ? 'critical' : heapUsed >= highBytes ? 'high' : 'normal'
+
+    if (level === 'normal') {
+      dumped.clear()
+      return
+    }
+
+    if (dumped.has(level) || inFlight.has(level)) {
+      return
+    }
+
+    inFlight.add(level)
+
+    // Prune Ink content caches before dump/exit — half on 'high' (recoverable),
+    // full on 'critical' (post-dump RSS reduction, keeps user running).
+    // Deferred import keeps `@nastechai/ink` off the cold-start critical path;
+    // by the time a tick fires 10s after launch the app has already loaded
+    // the same module, so this resolves instantly from the ESM cache.
+    try {
+      try {
+        const evictInkCaches = await _ensureEvictInkCaches()
+        evictInkCaches(level === 'critical' ? 'all' : 'half')
+      } catch {
+        // Best-effort: if the dynamic import fails for any reason we still
+        // continue to the heap dump below so the user gets diagnostics.
+      }
+
+      dumped.add(level)
+      const dump = await performHeapDump(level === 'critical' ? 'auto-critical' : 'auto-high').catch(() => null)
+      const snap: MemorySnapshot = { heapUsed, level, rss }
+
+      ;(level === 'critical' ? onCritical : onHigh)?.(snap, dump)
+    } finally {
+      inFlight.delete(level)
+    }
+  }
+
+  const handle = setInterval(() => void tick(), intervalMs)
+
+  handle.unref?.()
+
+  return () => clearInterval(handle)
+}

package/src/lib/messages.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest'
+
+import { appendTranscriptMessage } from './messages.js'
+
+describe('appendTranscriptMessage', () => {
+  it('merges adjacent tool-only shelves into one transcript row', () => {
+    const out = appendTranscriptMessage([{ kind: 'trail', role: 'system', text: '', tools: ['Terminal("one") ✓'] }], {
+      kind: 'trail',
+      role: 'system',
+      text: '',
+      tools: ['Terminal("two") ✓']
+    })
+
+    expect(out).toEqual([
+      { kind: 'trail', role: 'system', text: '', tools: ['Terminal("one") ✓', 'Terminal("two") ✓'] }
+    ])
+  })
+
+  it('merges tool shelves into the nearest thinking shelf', () => {
+    const out = appendTranscriptMessage(
+      [{ kind: 'trail', role: 'system', text: '', thinking: 'plan', tools: ['Terminal("one") ✓'] }],
+      { kind: 'trail', role: 'system', text: '', tools: ['Terminal("two") ✓'] }
+    )
+
+    expect(out).toEqual([
+      { kind: 'trail', role: 'system', text: '', thinking: 'plan', tools: ['Terminal("one") ✓', 'Terminal("two") ✓'] }
+    ])
+  })
+})

package/src/lib/messages.ts

@@ -0,0 +1,8 @@
+import type { Msg, Role } from '../types.js'
+
+import { appendToolShelfMessage } from './liveProgress.js'
+
+export const appendTranscriptMessage = (prev: Msg[], msg: Msg): Msg[] => appendToolShelfMessage(prev, msg)
+
+export const upsert = (prev: Msg[], role: Role, text: string): Msg[] =>
+  prev.at(-1)?.role === role ? [...prev.slice(0, -1), { role, text }] : [...prev, { role, text }]