nastech-tui 0.0.1

package/src/app/createSlashHandler.ts

@@ -0,0 +1,130 @@
+import { parseSlashCommand } from '../domain/slash.js'
+import type { SlashExecResponse } from '../gatewayTypes.js'
+import { asCommandDispatch, rpcErrorMessage } from '../lib/rpc.js'
+
+import type { SlashHandlerContext } from './interfaces.js'
+import { findSlashCommand } from './slash/registry.js'
+import type { SlashRunCtx } from './slash/types.js'
+import { getUiState } from './uiStore.js'
+
+export function createSlashHandler(ctx: SlashHandlerContext): (cmd: string) => boolean {
+  const { gw } = ctx.gateway
+  const { catalog } = ctx.local
+  const { page, send, sys } = ctx.transcript
+
+  const handler = (cmd: string): boolean => {
+    const flight = ++ctx.slashFlightRef.current
+    const ui = getUiState()
+    const sid = ui.sid
+    const parsed = parseSlashCommand(cmd)
+    const argTail = parsed.arg ? ` ${parsed.arg}` : ''
+
+    const stale = () => flight !== ctx.slashFlightRef.current || getUiState().sid !== sid
+
+    const guarded =
+      <T>(fn: (r: T) => void) =>
+      (r: null | T): void => {
+        if (!stale() && r) {
+          fn(r)
+        }
+      }
+
+    const guardedErr = (e: unknown) => {
+      if (!stale()) {
+        sys(`error: ${rpcErrorMessage(e)}`)
+      }
+    }
+
+    const runCtx: SlashRunCtx = { ...ctx, flight, guarded, guardedErr, sid, stale, ui }
+
+    const found = findSlashCommand(parsed.name)
+
+    if (found) {
+      found.run(parsed.arg, runCtx, cmd)
+
+      return true
+    }
+
+    if (catalog?.canon) {
+      const needle = `/${parsed.name}`.toLowerCase()
+      const exact = Object.entries(catalog.canon).find(([alias]) => alias.toLowerCase() === needle)?.[1]
+
+      if (exact) {
+        if (exact.toLowerCase() !== needle) {
+          return handler(`${exact}${argTail}`)
+        }
+      } else {
+        const matches = [
+          ...new Set(
+            Object.entries(catalog.canon)
+              .filter(([alias]) => alias.startsWith(needle))
+              .map(([, canon]) => canon)
+          )
+        ]
+
+        if (matches.length === 1 && matches[0]!.toLowerCase() !== needle) {
+          return handler(`${matches[0]}${argTail}`)
+        }
+
+        if (matches.length > 1) {
+          sys(`ambiguous command: ${matches.slice(0, 6).join(', ')}${matches.length > 6 ? ', …' : ''}`)
+
+          return true
+        }
+      }
+    }
+
+    gw.request<SlashExecResponse>('slash.exec', { command: cmd.slice(1), session_id: sid })
+      .then(r => {
+        if (stale()) {
+          return
+        }
+
+        const body = r?.output || `/${parsed.name}: no output`
+        const text = r?.warning ? `warning: ${r.warning}\n${body}` : body
+        const long = text.length > 180 || text.split('\n').filter(Boolean).length > 2
+
+        long ? page(text, parsed.name[0]!.toUpperCase() + parsed.name.slice(1)) : sys(text)
+      })
+      .catch(() => {
+        gw.request('command.dispatch', { arg: parsed.arg, name: parsed.name, session_id: sid })
+          .then((raw: unknown) => {
+            if (stale()) {
+              return
+            }
+
+            const d = asCommandDispatch(raw)
+
+            if (!d) {
+              return sys('error: invalid response: command.dispatch')
+            }
+
+            if (d.type === 'exec' || d.type === 'plugin') {
+              return sys(d.output || '(no output)')
+            }
+
+            if (d.type === 'alias') {
+              return handler(`/${d.target}${argTail}`)
+            }
+
+            if (d.type === 'skill') {
+              sys(`⚡ loading skill: ${d.name}`)
+
+              return d.message?.trim() ? send(d.message) : sys(`/${parsed.name}: skill payload missing message`)
+            }
+
+            if (d.type === 'send') {
+              if (d.notice?.trim()) {
+                sys(d.notice)
+              }
+              return d.message?.trim() ? send(d.message) : sys(`/${parsed.name}: empty message`)
+            }
+          })
+          .catch(guardedErr)
+      })
+
+    return true
+  }
+
+  return handler
+}

package/src/app/delegationStore.ts

@@ -0,0 +1,77 @@
+import { atom } from 'nanostores'
+
+import type { DelegationStatusResponse } from '../gatewayTypes.js'
+
+export interface DelegationState {
+  // Last known caps from `delegation.status` RPC.  null until fetched.
+  maxConcurrentChildren: null | number
+  maxSpawnDepth: null | number
+  // True when spawning is globally paused (see tools/delegate_tool.py).
+  paused: boolean
+  // Monotonic clock of the last successful status fetch.
+  updatedAt: null | number
+}
+
+const buildState = (): DelegationState => ({
+  maxConcurrentChildren: null,
+  maxSpawnDepth: null,
+  paused: false,
+  updatedAt: null
+})
+
+export const $delegationState = atom<DelegationState>(buildState())
+
+export const getDelegationState = () => $delegationState.get()
+
+export const patchDelegationState = (next: Partial<DelegationState>) =>
+  $delegationState.set({ ...$delegationState.get(), ...next })
+
+export const resetDelegationState = () => $delegationState.set(buildState())
+
+// ── Overlay accordion open-state ──────────────────────────────────────
+//
+// Lifted out of OverlaySection's local useState so collapse choices
+// survive:
+//   - navigating to a different subagent (Detail remounts)
+//   - switching list ↔ detail mode (Detail unmounts in list mode)
+//   - walking history (←/→)
+// Keyed by section title; missing entries fall back to the section's
+// `defaultOpen` prop.
+
+export const $overlaySectionsOpen = atom<Record<string, boolean>>({})
+
+export const toggleOverlaySection = (title: string, defaultOpen: boolean) => {
+  const state = $overlaySectionsOpen.get()
+  const current = title in state ? state[title]! : defaultOpen
+
+  $overlaySectionsOpen.set({ ...state, [title]: !current })
+}
+
+export const getOverlaySectionOpen = (title: string, defaultOpen: boolean): boolean => {
+  const state = $overlaySectionsOpen.get()
+
+  return title in state ? state[title]! : defaultOpen
+}
+
+/** Merge a raw RPC response into the store.  Tolerant of partial/omitted fields. */
+export const applyDelegationStatus = (r: DelegationStatusResponse | null | undefined) => {
+  if (!r) {
+    return
+  }
+
+  const patch: Partial<DelegationState> = { updatedAt: Date.now() }
+
+  if (typeof r.max_spawn_depth === 'number') {
+    patch.maxSpawnDepth = r.max_spawn_depth
+  }
+
+  if (typeof r.max_concurrent_children === 'number') {
+    patch.maxConcurrentChildren = r.max_concurrent_children
+  }
+
+  if (typeof r.paused === 'boolean') {
+    patch.paused = r.paused
+  }
+
+  patchDelegationState(patch)
+}

package/src/app/gatewayContext.tsx

@@ -0,0 +1,19 @@
+import { createContext, useContext } from 'react'
+
+import type { GatewayProviderProps, GatewayServices } from './interfaces.js'
+
+const GatewayContext = createContext<GatewayServices | null>(null)
+
+export function GatewayProvider({ children, value }: GatewayProviderProps) {
+  return <GatewayContext.Provider value={value}>{children}</GatewayContext.Provider>
+}
+
+export function useGateway() {
+  const value = useContext(GatewayContext)
+
+  if (!value) {
+    throw new Error('GatewayContext missing')
+  }
+
+  return value
+}

package/src/app/gatewayRecovery.ts

@@ -0,0 +1,35 @@
+// Crash-recovery budget for the gateway exit handler. A gateway that
+// crash-loops on startup must not let the TUI spawn-storm, so respawn+resume
+// attempts are capped to GATEWAY_RECOVERY_LIMIT within a sliding
+// GATEWAY_RECOVERY_WINDOW_MS; past the budget the app falls back to the inert
+// "gateway exited" state. Kept pure (no refs/UI) so the bound — including the
+// crash-loop case — is unit-testable.
+export const GATEWAY_RECOVERY_LIMIT = 3
+export const GATEWAY_RECOVERY_WINDOW_MS = 60_000
+
+export interface RecoveryPlan {
+  // Attempt timestamps to persist (the pruned window, plus `now` iff recovering).
+  attempts: number[]
+  recover: boolean
+  // Session to resume — the live sid, or the not-yet-consumed recovery target
+  // when the live sid was already cleared by a prior exit.
+  sid: null | string
+}
+
+// Decide whether to respawn+resume after a gateway death. `liveSid` is the
+// current session (nulled on the first exit); `recoverSid` is a pending
+// recovery target carried across a respawn that died before gateway.ready —
+// so a startup crash-loop keeps retrying the same session up to the budget
+// instead of stranding it after one attempt.
+export function planGatewayRecovery(
+  liveSid: null | string,
+  recoverSid: null | string,
+  attempts: number[],
+  now: number
+): RecoveryPlan {
+  const sid = liveSid ?? recoverSid
+  const recent = attempts.filter(t => now - t < GATEWAY_RECOVERY_WINDOW_MS)
+  const recover = Boolean(sid) && recent.length < GATEWAY_RECOVERY_LIMIT
+
+  return { attempts: recover ? [...recent, now] : recent, recover, sid }
+}

package/src/app/inputSelectionStore.ts

@@ -0,0 +1,15 @@
+import { atom } from 'nanostores'
+
+export interface InputSelection {
+  clear: () => void
+  collapseToEnd: () => void
+  end: number
+  start: number
+  value: string
+}
+
+export const $inputSelection = atom<InputSelection | null>(null)
+
+export const setInputSelection = (next: InputSelection | null) => $inputSelection.set(next)
+
+export const getInputSelection = () => $inputSelection.get()

package/src/app/interfaces.ts

@@ -0,0 +1,394 @@
+import type { MouseTrackingMode, ScrollBoxHandle } from '@nastechai/ink'
+import type { MutableRefObject, ReactNode, RefObject, SetStateAction } from 'react'
+
+import type { PasteEvent } from '../components/textInput.js'
+import type { GatewayClient } from '../gatewayClient.js'
+import type { ImageAttachResponse, SessionCloseResponse } from '../gatewayTypes.js'
+import type { ParsedVoiceRecordKey } from '../lib/platform.js'
+import type { RpcResult } from '../lib/rpc.js'
+import type { Theme } from '../theme.js'
+import type {
+  ApprovalReq,
+  ClarifyReq,
+  ConfirmReq,
+  DetailsMode,
+  Msg,
+  PanelSection,
+  SecretReq,
+  SectionVisibility,
+  SessionInfo,
+  SlashCatalog,
+  SudoReq,
+  Usage
+} from '../types.js'
+
+export interface StateSetter<T> {
+  (value: SetStateAction<T>): void
+}
+
+export type StatusBarMode = 'bottom' | 'off' | 'top'
+
+export type BusyInputMode = 'interrupt' | 'queue' | 'steer'
+
+// Single source of truth for indicator style names.  Union type is
+// derived from this tuple so adding/removing a style only touches one
+// line — `useConfigSync` (validation) and `session.ts` (slash arg
+// validation + usage hint) both import it.
+export const INDICATOR_STYLES = ['ascii', 'emoji', 'kaomoji', 'unicode'] as const
+export type IndicatorStyle = (typeof INDICATOR_STYLES)[number]
+export const DEFAULT_INDICATOR_STYLE: IndicatorStyle = 'kaomoji'
+
+export interface SelectionApi {
+  captureScrolledRows: (firstRow: number, lastRow: number, side: 'above' | 'below') => void
+  clearSelection: () => void
+  copySelection: () => Promise<string>
+  copySelectionNoClear: () => Promise<string>
+  getState: () => unknown
+  version: () => number
+  shiftAnchor: (dRow: number, minRow: number, maxRow: number) => void
+  shiftSelection: (dRow: number, minRow: number, maxRow: number) => void
+}
+
+export interface CompletionItem {
+  display: string
+  meta?: string
+  text: string
+}
+
+export interface GatewayRpc {
+  <T extends RpcResult = RpcResult>(method: string, params?: Record<string, unknown>): Promise<null | T>
+}
+
+export interface GatewayServices {
+  gw: GatewayClient
+  rpc: GatewayRpc
+}
+
+export interface GatewayProviderProps {
+  children: ReactNode
+  value: GatewayServices
+}
+
+export interface OverlayState {
+  agents: boolean
+  agentsInitialHistoryIndex: number
+  approval: ApprovalReq | null
+  clarify: ClarifyReq | null
+  confirm: ConfirmReq | null
+  modelPicker: boolean
+  pager: null | PagerState
+  picker: boolean
+  secret: null | SecretReq
+  sessions: boolean
+  skillsHub: boolean
+  sudo: null | SudoReq
+}
+
+export interface PagerState {
+  lines: string[]
+  offset: number
+  title?: string
+}
+
+export interface TranscriptRow {
+  index: number
+  key: string
+  msg: Msg
+}
+
+export interface UiState {
+  bgTasks: Set<string>
+  busy: boolean
+  busyInputMode: BusyInputMode
+  compact: boolean
+  detailsMode: DetailsMode
+  detailsModeCommandOverride: boolean
+  info: null | SessionInfo
+  liveSessionCount: number
+  inlineDiffs: boolean
+  mouseTracking: MouseTrackingMode
+  pasteCollapseLines: number
+  pasteCollapseChars: number
+
+  sections: SectionVisibility
+  showCost: boolean
+  showReasoning: boolean
+  indicatorStyle: IndicatorStyle
+  sid: null | string
+  status: string
+  statusBar: StatusBarMode
+  streaming: boolean
+  theme: Theme
+  usage: Usage
+}
+
+export interface VirtualHistoryState {
+  bottomSpacer: number
+  end: number
+  measureRef: (key: string) => (el: unknown) => void
+  offsets: ArrayLike<number>
+  start: number
+  topSpacer: number
+}
+
+export interface ComposerPasteResult {
+  cursor: number
+  value: string
+}
+
+export type MaybePromise<T> = Promise<T> | T
+
+export interface ComposerActions {
+  clearIn: () => void
+  dequeue: () => string | undefined
+  enqueue: (text: string) => void
+  handleTextPaste: (event: PasteEvent) => MaybePromise<ComposerPasteResult | null>
+  openEditor: () => Promise<void>
+  pushHistory: (text: string) => void
+  removeQueue: (index: number) => void
+  replaceQueue: (index: number, text: string) => void
+  setCompIdx: StateSetter<number>
+  setHistoryIdx: StateSetter<null | number>
+  setInput: StateSetter<string>
+  setInputBuf: StateSetter<string[]>
+  setPasteSnips: StateSetter<PasteSnippet[]>
+  setQueueEdit: (index: null | number) => void
+  syncQueue: () => void
+}
+
+export interface ComposerRefs {
+  historyDraftRef: MutableRefObject<string>
+  historyRef: MutableRefObject<string[]>
+  queueEditRef: MutableRefObject<null | number>
+  queueRef: MutableRefObject<string[]>
+  submitRef: MutableRefObject<(value: string) => void>
+}
+
+export interface ComposerState {
+  compIdx: number
+  compReplace: number
+  completions: CompletionItem[]
+  historyIdx: null | number
+  input: string
+  inputBuf: string[]
+  pasteSnips: PasteSnippet[]
+  queueEditIdx: null | number
+  queuedDisplay: string[]
+}
+
+export interface UseComposerStateOptions {
+  gw: GatewayClient
+  onClipboardPaste: (quiet?: boolean) => Promise<void> | void
+  onImageAttached?: (info: ImageAttachResponse) => void
+  submitRef: MutableRefObject<(value: string) => void>
+}
+
+export interface UseComposerStateResult {
+  actions: ComposerActions
+  refs: ComposerRefs
+  state: ComposerState
+}
+
+export interface InputHandlerActions {
+  answerClarify: (answer: string) => void
+  appendMessage: (msg: Msg) => void
+  die: () => void
+  dispatchSubmission: (full: string) => void
+  guardBusySessionSwitch: (what?: string) => boolean
+  newSession: (msg?: string, title?: string) => void
+  sys: (text: string) => void
+}
+
+export interface InputHandlerContext {
+  actions: InputHandlerActions
+  composer: {
+    actions: ComposerActions
+    refs: ComposerRefs
+    state: ComposerState
+  }
+  gateway: GatewayServices
+  terminal: {
+    hasSelection: boolean
+    scrollRef: RefObject<null | ScrollBoxHandle>
+    scrollWithSelection: (delta: number) => void
+    selection: SelectionApi
+    stdout?: NodeJS.WriteStream
+  }
+  voice: {
+    enabled: boolean
+    recordKey: ParsedVoiceRecordKey
+    recording: boolean
+    setProcessing: StateSetter<boolean>
+    setRecording: StateSetter<boolean>
+    setVoiceEnabled: StateSetter<boolean>
+    setVoiceTts: StateSetter<boolean>
+  }
+  wheelStep: number
+}
+
+export interface InputHandlerResult {
+  pagerPageSize: number
+}
+
+export interface GatewayEventHandlerContext {
+  composer: {
+    setInput: StateSetter<string>
+  }
+  gateway: GatewayServices
+  session: {
+    STARTUP_RESUME_ID: string
+    colsRef: MutableRefObject<number>
+    newSession: (msg?: string, title?: string) => void
+    resetSession: () => void
+    resumeById: (id: string) => void
+    setCatalog: StateSetter<null | SlashCatalog>
+  }
+  submission: {
+    submitRef: MutableRefObject<(value: string) => void>
+  }
+  system: {
+    bellOnComplete: boolean
+    stdout?: NodeJS.WriteStream
+    sys: (text: string) => void
+  }
+  transcript: {
+    appendMessage: (msg: Msg) => void
+    panel: (title: string, sections: PanelSection[]) => void
+    setHistoryItems: StateSetter<Msg[]>
+  }
+  voice: {
+    setProcessing: StateSetter<boolean>
+    setRecording: StateSetter<boolean>
+    setVoiceEnabled: StateSetter<boolean>
+    setVoiceTts: StateSetter<boolean>
+  }
+}
+
+export interface SlashHandlerContext {
+  composer: {
+    enqueue: (text: string) => void
+    hasSelection: boolean
+    paste: (quiet?: boolean) => void
+    queueRef: MutableRefObject<string[]>
+    selection: SelectionApi
+    setInput: StateSetter<string>
+  }
+  gateway: GatewayServices
+  local: {
+    catalog: null | SlashCatalog
+    getHistoryItems: () => Msg[]
+    getLastUserMsg: () => string
+    maybeWarn: (value: unknown) => void
+    setCatalog: StateSetter<null | SlashCatalog>
+  }
+  session: {
+    closeSession: (targetSid?: null | string) => Promise<unknown>
+    die: () => void
+    dieWithCode: (code: number) => void
+    guardBusySessionSwitch: (what?: string) => boolean
+    newLiveSession: (msg?: string, title?: string) => void
+    newSession: (msg?: string, title?: string) => void
+    resetVisibleHistory: (info?: null | SessionInfo) => void
+    resumeById: (id: string) => void
+    setSessionStartedAt: StateSetter<number>
+  }
+  slashFlightRef: MutableRefObject<number>
+  transcript: {
+    page: (text: string, title?: string) => void
+    panel: (title: string, sections: PanelSection[]) => void
+    send: (text: string) => void
+    setHistoryItems: StateSetter<Msg[]>
+    sys: (text: string) => void
+    trimLastExchange: (items: Msg[]) => Msg[]
+  }
+  voice: {
+    setVoiceEnabled: StateSetter<boolean>
+    setVoiceRecordKey: (v: ParsedVoiceRecordKey) => void
+    setVoiceTts: StateSetter<boolean>
+  }
+}
+
+export interface AppLayoutActions {
+  answerApproval: (choice: string) => void
+  answerClarify: (answer: string) => void
+  answerSecret: (value: string) => void
+  answerSudo: (pw: string) => void
+  clearSelection: () => void
+  activateLiveSession: (id: string) => void
+  closeLiveSession: (id: string) => Promise<null | SessionCloseResponse>
+  newLiveSession: () => void
+  newPromptSession: (prompt: string, modelArg?: string) => void
+  onModelSelect: (value: string) => void
+  resumeById: (id: string) => void
+  setStickyPrompt: (value: string) => void
+}
+
+export interface AppLayoutComposerProps {
+  cols: number
+  compIdx: number
+  completions: CompletionItem[]
+  empty: boolean
+  handleTextPaste: (event: PasteEvent) => MaybePromise<ComposerPasteResult | null>
+  input: string
+  inputBuf: string[]
+  pagerPageSize: number
+  queueEditIdx: null | number
+  queuedDisplay: string[]
+  submit: (value: string) => void
+  updateInput: StateSetter<string>
+  voiceRecordKey: ParsedVoiceRecordKey
+}
+
+export interface AppLayoutProgressProps {
+  showProgressArea: boolean
+}
+
+export interface AppLayoutStatusProps {
+  cwdLabel: string
+  goodVibesTick: number
+  sessionStartedAt: null | number
+  showStickyPrompt: boolean
+  statusColor: string
+  stickyPrompt: string
+  turnStartedAt: null | number
+  voiceLabel: string
+}
+
+export interface AppLayoutTranscriptProps {
+  historyItems: Msg[]
+  scrollRef: RefObject<null | ScrollBoxHandle>
+  virtualHistory: VirtualHistoryState
+  virtualRows: TranscriptRow[]
+}
+
+export interface AppLayoutProps {
+  actions: AppLayoutActions
+  composer: AppLayoutComposerProps
+  mouseTracking: MouseTrackingMode
+  progress: AppLayoutProgressProps
+  status: AppLayoutStatusProps
+  transcript: AppLayoutTranscriptProps
+}
+
+export interface AppOverlaysProps {
+  cols: number
+  compIdx: number
+  completions: CompletionItem[]
+  onApprovalChoice: (choice: string) => void
+  onClarifyAnswer: (value: string) => void
+  onActiveSessionSelect: (sessionId: string) => void
+  onActiveSessionClose: (sessionId: string) => Promise<null | SessionCloseResponse>
+  onModelSelect: (value: string) => void
+  onNewLiveSession: () => void
+  onNewPromptSession: (prompt: string, modelArg?: string) => void
+  onPickerSelect: (sessionId: string) => void
+  onSecretSubmit: (value: string) => void
+  onSudoSubmit: (pw: string) => void
+  pagerPageSize: number
+}
+
+export interface PasteSnippet {
+  label: string
+  path?: string
+  text: string
+}