nastech-tui 0.0.1

package/src/lib/platform.ts

@@ -0,0 +1,409 @@
+/** Platform-aware keybinding helpers.
+ *
+ * On macOS the "action" modifier is Cmd. Modern terminals that support kitty
+ * keyboard protocol report Cmd as `key.super`; legacy terminals often surface it
+ * as `key.meta`. Some macOS terminals also translate Cmd+Left/Right/Backspace
+ * into readline-style Ctrl+A/Ctrl+E/Ctrl+U before the app sees them.
+ * On other platforms the action modifier is Ctrl.
+ * Ctrl+C stays the interrupt key on macOS. On non-mac terminals it can also
+ * copy an active TUI selection, matching common terminal selection behavior.
+ */
+
+export const isMac = process.platform === 'darwin'
+
+/** True when the platform action-modifier is pressed (Cmd on macOS, Ctrl elsewhere). */
+export const isActionMod = (key: { ctrl: boolean; meta: boolean; super?: boolean }): boolean =>
+  isMac ? key.meta || key.super === true : key.ctrl
+
+/**
+ * Accept raw Ctrl+<letter> as an action shortcut on macOS, where `isActionMod`
+ * otherwise means Cmd. Two motivations:
+ *   - Some macOS terminals rewrite Cmd navigation/deletion into readline control
+ *     keys (Cmd+Left → Ctrl+A, Cmd+Right → Ctrl+E, Cmd+Backspace → Ctrl+U).
+ *   - Ctrl+K (kill-to-end) and Ctrl+W (delete-word-back) are standard readline
+ *     bindings that users expect to work regardless of platform, even though
+ *     no terminal rewrites Cmd into them.
+ */
+export const isMacActionFallback = (
+  key: { ctrl: boolean; meta: boolean; super?: boolean },
+  ch: string,
+  target: 'a' | 'e' | 'u' | 'k' | 'w'
+): boolean => isMac && key.ctrl && !key.meta && key.super !== true && ch.toLowerCase() === target
+
+/** Match action-modifier + a single character (case-insensitive). */
+export const isAction = (key: { ctrl: boolean; meta: boolean; super?: boolean }, ch: string, target: string): boolean =>
+  isActionMod(key) && ch.toLowerCase() === target
+
+export const isRemoteShell = (env: NodeJS.ProcessEnv = process.env): boolean =>
+  Boolean(env.SSH_CONNECTION || env.SSH_CLIENT || env.SSH_TTY)
+
+export const isCopyShortcut = (
+  key: { ctrl: boolean; meta: boolean; super?: boolean },
+  ch: string,
+  env: NodeJS.ProcessEnv = process.env
+): boolean =>
+  ch.toLowerCase() === 'c' &&
+  (isAction(key, ch, 'c') ||
+    (isRemoteShell(env) && (key.meta || key.super === true)) ||
+    // VS Code/Cursor/Windsurf terminal setup forwards Cmd+C as a CSI-u
+    // sequence with the super bit plus a benign ctrl bit. Accept that shape
+    // even though raw Ctrl+C should remain interrupt on local macOS.
+    (isMac && key.ctrl && (key.meta || key.super === true)))
+
+/**
+ * Voice recording toggle key — configurable via ``voice.record_key`` in
+ * ``config.yaml`` (default ``ctrl+b``).
+ *
+ * Documented in tips.py, the Python CLI prompt_toolkit handler, and the
+ * config.yaml default. The TUI honours the same config knob (#18994);
+ * when ``voice.record_key`` is e.g. ``ctrl+o`` the TUI binds Ctrl+O.
+ *
+ * Only the documented default (``ctrl+b``) additionally accepts the
+ * macOS action modifier (Cmd+B) — custom bindings like ``ctrl+o``
+ * require the literal Ctrl bit so Cmd+O can't steal the shortcut.
+ */
+export type VoiceRecordKeyMod = 'alt' | 'ctrl' | 'super'
+
+/** Named (multi-character) keys we support, matching the CLI's
+ * prompt_toolkit binding shape (``c-space``, ``c-enter``, etc.) so a
+ * config value like ``ctrl+space`` binds in both runtimes. */
+export type VoiceRecordKeyNamed = 'backspace' | 'delete' | 'enter' | 'escape' | 'space' | 'tab'
+
+export interface ParsedVoiceRecordKey {
+  /** Single character (``'b'``, ``'o'``) when ``named`` is undefined,
+   * otherwise the named-key token (``'space'``, ``'enter'``…). Kept as
+   * one field for back-compat with the v1 ``{ ch, mod, raw }`` shape. */
+  ch: string
+  mod: VoiceRecordKeyMod
+  named?: VoiceRecordKeyNamed
+  raw: string
+}
+
+export const DEFAULT_VOICE_RECORD_KEY: ParsedVoiceRecordKey = {
+  ch: 'b',
+  mod: 'ctrl',
+  raw: 'ctrl+b'
+}
+
+/** Modifier aliases.
+ *
+ * ``meta`` / ``cmd`` / ``command`` are intentionally absent.
+ * nastech-ink sets ``key.meta`` for plain Alt/Option on every platform
+ * AND for Cmd on some legacy macOS terminals (Terminal.app without
+ * kitty-protocol passthrough). Accepting any of those as a literal
+ * modifier would produce a display/binding mismatch — a config like
+ * ``cmd+b`` would render as ``Cmd+B`` but silently fire on Alt+B, or
+ * never fire at all on legacy terminals even though the UI advertises
+ * it (Copilot round-6 review on #19835). Users on modern kitty-style
+ * terminals (iTerm2 CSI-u, Ghostty, Kitty, WezTerm, Alacritty) spell
+ * the platform action modifier ``super`` / ``win``, which match the
+ * unambiguous ``key.super`` bit. macOS users on Terminal.app stick
+ * with the documented ``ctrl+b``.
+ *
+ * Cross-runtime parity: the ``ctrl`` / ``control`` / ``alt`` / ``option`` /
+ * ``opt`` spellings are normalized identically in the classic CLI
+ * (``nastech_cli/voice.py::normalize_voice_record_key_for_prompt_toolkit``)
+ * so one ``voice.record_key`` value binds the same shortcut in both
+ * runtimes (Copilot round-9 review on #19835). The ``super`` /
+ * ``win`` / ``windows`` spellings are TUI-only — prompt_toolkit has no
+ * super modifier, so the CLI falls back to the documented default and
+ * logs a warning at startup (Copilot round-11 review on #19835). */
+const _MOD_ALIASES: Record<string, VoiceRecordKeyMod> = {
+  alt: 'alt',
+  control: 'ctrl',
+  ctrl: 'ctrl',
+  option: 'alt',
+  opt: 'alt',
+  super: 'super',
+  win: 'super',
+  windows: 'super'
+}
+
+/** Map config-string named tokens to the canonical name used at match time.
+ *
+ * Aliases mirror what prompt_toolkit accepts (``return`` ↔ ``enter``,
+ * ``esc`` ↔ ``escape``) so a config that round-trips through the CLI also
+ * binds in the TUI. */
+const _NAMED_KEY_ALIASES: Record<string, VoiceRecordKeyNamed> = {
+  backspace: 'backspace',
+  bs: 'backspace',
+  del: 'delete',
+  delete: 'delete',
+  enter: 'enter',
+  esc: 'escape',
+  escape: 'escape',
+  ret: 'enter',
+  return: 'enter',
+  space: 'space',
+  spc: 'space',
+  tab: 'tab'
+}
+
+/** ``useInputHandlers()`` intercepts these unconditionally before the
+ * voice check runs, so a binding like ``ctrl+c`` (interrupt),
+ * ``ctrl+d`` (quit), or ``ctrl+l`` (clear screen) would be advertised
+ * in /voice status but never fire push-to-talk. Reject at parse time
+ * so the user gets the documented Ctrl+B instead of a dead shortcut
+ * (Copilot round-4 review on #19835).
+ *
+ * ``ctrl+x`` is intentionally NOT here — it's only claimed during
+ * queue-edit (``queueEditIdx !== null``), so the voice binding works
+ * for most of the session and matches CLI parity for ``ctrl+<letter>``
+ * bindings (Copilot round-8 review on #19835). */
+const _RESERVED_CTRL_CHARS = new Set(['c', 'd', 'l'])
+
+/** On macOS the action-modifier intercepts these editor chords via
+ * ``isCopyShortcut`` / ``isAction`` in ``useInputHandlers()``:
+ *  - super+c → copy
+ *  - super+d → exit
+ *  - super+l → clear screen
+ *  - super+v → paste (also claimed at the TextInput layer)
+ * On Linux/Windows those globals key off Ctrl instead of Super, so
+ * super+<letter> bindings don't collide. Gate the rejection to darwin
+ * at parse time so kitty/CSI-u ``super+<key>`` configs still work for
+ * non-mac users (Copilot round-8 review on #19835). */
+const _RESERVED_SUPER_CHARS = new Set(['c', 'd', 'l', 'v'])
+
+/** On macOS ``isActionMod`` accepts ``key.meta`` as the action
+ * modifier — but nastech-ink reports Alt as ``key.meta`` on many
+ * terminals. So on darwin a configured ``alt+c`` / ``alt+d`` / ``alt+l``
+ * gets swallowed by ``isCopyShortcut`` / ``isAction`` before the voice
+ * check runs. Block at parse time so /voice status doesn't advertise
+ * a shortcut that actually copies / quits / clears (Copilot round-12
+ * review on #19835). */
+const _RESERVED_ALT_CHARS_MAC = new Set(['c', 'd', 'l'])
+
+interface RuntimeKeyEvent {
+  alt?: boolean
+  backspace?: boolean
+  ctrl: boolean
+  delete?: boolean
+  escape?: boolean
+  meta: boolean
+  return?: boolean
+  shift?: boolean
+  super?: boolean
+  tab?: boolean
+}
+
+/** Match an ink ``key`` event against a parsed named key. The ink runtime
+ * sets one boolean per named key; ``space`` is a printable char so it
+ * arrives as ``ch === ' '`` rather than a dedicated ``key.space`` flag. */
+const _matchesNamedKey = (
+  named: VoiceRecordKeyNamed,
+  key: RuntimeKeyEvent,
+  ch: string
+): boolean => {
+  switch (named) {
+    case 'backspace':
+      return key.backspace === true
+    case 'delete':
+      return key.delete === true
+    case 'enter':
+      return key.return === true
+    case 'escape':
+      return key.escape === true
+    case 'space':
+      return ch === ' '
+    case 'tab':
+      return key.tab === true
+  }
+}
+
+/**
+ * Parse a config-string voice record key like ``ctrl+b`` / ``alt+r`` /
+ * ``ctrl+space`` into ``{mod, ch, named?}``. Accepts single characters
+ * AND the named tokens declared in ``_NAMED_KEY_ALIASES`` (``space``,
+ * ``enter``/``return``, ``tab``, ``escape``/``esc``, ``backspace``,
+ * ``delete``) — matching the keys prompt_toolkit accepts on the CLI
+ * side via the ``c-<name>`` rewrite in ``cli.py``.
+ *
+ * Accepts ``unknown`` because the source is raw YAML via
+ * ``config.get full`` — a hand-edited ``voice.record_key: 1`` or
+ * ``voice.record_key: true`` would otherwise crash ``.trim()`` on a
+ * non-string scalar (Copilot round-3 review on #19835). Non-string /
+ * empty / unrecognised values fall back to the documented Ctrl+B
+ * default so a typo never silently disables the shortcut.
+ */
+export const parseVoiceRecordKey = (raw: unknown): ParsedVoiceRecordKey => {
+  if (typeof raw !== 'string') {
+    return DEFAULT_VOICE_RECORD_KEY
+  }
+
+  const lower = raw.trim().toLowerCase()
+
+  if (!lower) {
+    return DEFAULT_VOICE_RECORD_KEY
+  }
+
+  const parts = lower.split('+').map(p => p.trim()).filter(Boolean)
+
+  if (!parts.length) {
+    return DEFAULT_VOICE_RECORD_KEY
+  }
+
+  const last = parts[parts.length - 1]
+  const modCandidates = parts.slice(0, -1)
+
+  // Reject multi-modifier chords (``ctrl+alt+r``, ``cmd+ctrl+b``) rather
+  // than silently dropping the extra modifier — the previous
+  // single-token validator made a typo bind a different shortcut than
+  // the user configured (Copilot round-3 review on #19835). The classic
+  // CLI only supports single-modifier bindings via prompt_toolkit's
+  // ``c-x`` / ``a-x`` rewrite in ``cli.py``, so this matches CLI parity.
+  if (modCandidates.length > 1) {
+    return DEFAULT_VOICE_RECORD_KEY
+  }
+
+  // Require an explicit modifier. A bare ``o`` / ``space`` / ``escape``
+  // has no sensible mapping: the CLI's prompt_toolkit binds the raw
+  // key (no rewrite) so bare-char configs would silently diverge
+  // between the two runtimes (Copilot round-4 review on #19835).
+  // Fall back to the documented default.
+  if (modCandidates.length === 0) {
+    return DEFAULT_VOICE_RECORD_KEY
+  }
+
+  const norm = _MOD_ALIASES[modCandidates[0]]
+
+  // Unknown modifier token (e.g. bare ``meta+b`` which is ambiguous on
+  // the wire) falls back to the documented default rather than
+  // silently coercing to Ctrl and producing a misleading bind.
+  if (!norm) {
+    return DEFAULT_VOICE_RECORD_KEY
+  }
+
+  const mod = norm
+
+  // Block bindings the TUI input handler intercepts before the voice
+  // check — ``ctrl+c`` / ``ctrl+d`` / ``ctrl+l`` would never actually
+  // fire push-to-talk, so advertising them in /voice status is a lie.
+  if (mod === 'ctrl' && last.length === 1 && _RESERVED_CTRL_CHARS.has(last)) {
+    return DEFAULT_VOICE_RECORD_KEY
+  }
+
+  // Same for ``super+c`` / ``super+d`` / ``super+l`` / ``super+v`` on
+  // macOS only — those are copy / exit / clear / paste and get claimed
+  // by ``isCopyShortcut`` / ``isAction`` / the TextInput paste layer
+  // before voice has a chance to toggle. On Linux/Windows the TUI
+  // globals key off Ctrl (not Super), so kitty/CSI-u ``super+<letter>``
+  // bindings stay usable for non-mac users.
+  if (isMac && mod === 'super' && last.length === 1 && _RESERVED_SUPER_CHARS.has(last)) {
+    return DEFAULT_VOICE_RECORD_KEY
+  }
+
+  // On macOS nastech-ink reports Alt as ``key.meta``, which ``isActionMod``
+  // accepts as the mac action modifier. So ``alt+c`` / ``alt+d`` / ``alt+l``
+  // collide with copy / exit / clear in ``useInputHandlers()`` before the
+  // voice check. Reject at parse time on darwin only — non-mac ``alt+<letter>``
+  // bindings are still usable (Copilot round-12 review on #19835).
+  if (isMac && mod === 'alt' && last.length === 1 && _RESERVED_ALT_CHARS_MAC.has(last)) {
+    return DEFAULT_VOICE_RECORD_KEY
+  }
+
+  if (last.length === 1) {
+    return { ch: last, mod, raw: lower }
+  }
+
+  const named = _NAMED_KEY_ALIASES[last]
+
+  if (named) {
+    return { ch: named, mod, named, raw: lower }
+  }
+
+  // Unknown multi-character token (e.g. typo'd ``ctrl+spcae``) — fall back
+  // to the doc default rather than silently disabling the binding.
+  return DEFAULT_VOICE_RECORD_KEY
+}
+
+/** Render a parsed key back as ``Ctrl+B`` / ``Ctrl+Space`` for status text.
+ *
+ * Platform-aware for the ``super`` modifier: renders ``Cmd`` on macOS and
+ * ``Super`` elsewhere. Previously rendered ``Cmd`` universally, which told
+ * Linux/Windows users the wrong modifier to press (Copilot review, round
+ * 2 on #19835). */
+export const formatVoiceRecordKey = (parsed: ParsedVoiceRecordKey): string => {
+  const modLabel =
+    parsed.mod === 'super' ? (isMac ? 'Cmd' : 'Super') : parsed.mod[0].toUpperCase() + parsed.mod.slice(1)
+  // Named tokens render in title case (Ctrl+Space, Ctrl+Enter); single
+  // chars render upper-case to match the existing Ctrl+B convention.
+  const keyLabel = parsed.named
+    ? parsed.named[0].toUpperCase() + parsed.named.slice(1)
+    : parsed.ch.toUpperCase()
+
+  return `${modLabel}+${keyLabel}`
+}
+
+/** Whether the parsed binding is the documented default (ctrl+b).
+ *
+ * Compare on the parsed spec rather than ``raw`` so semantically-equal
+ * aliases (``control+b``, ``ctrl + b``) still get the macOS Cmd+B
+ * muscle-memory fallback (Copilot review, round 2 on #19835). */
+const _isDefaultVoiceKey = (parsed: ParsedVoiceRecordKey): boolean =>
+  parsed.mod === DEFAULT_VOICE_RECORD_KEY.mod &&
+  parsed.ch === DEFAULT_VOICE_RECORD_KEY.ch &&
+  parsed.named === DEFAULT_VOICE_RECORD_KEY.named
+
+export const isVoiceToggleKey = (
+  key: RuntimeKeyEvent,
+  ch: string,
+  configured: ParsedVoiceRecordKey = DEFAULT_VOICE_RECORD_KEY
+): boolean => {
+  // Match the configured key first (single-char compare or named-key
+  // event-property check). Bail out before evaluating modifier shape
+  // so the wrong key never reaches the modifier guard.
+  if (configured.named) {
+    if (!_matchesNamedKey(configured.named, key, ch)) {
+      return false
+    }
+  } else if (ch.toLowerCase() !== configured.ch) {
+    return false
+  }
+
+  // The parser rejects multi-modifier configs (``ctrl+shift+b`` etc.),
+  // so at match time Shift must always be clear — otherwise
+  // ``ctrl+tab`` would also fire on Ctrl+Shift+Tab and ``alt+enter``
+  // on Alt+Shift+Enter, triggering a different chord than configured
+  // (Copilot round-5 review on #19835).
+  if (key.shift === true) {
+    return false
+  }
+
+  switch (configured.mod) {
+    case 'alt':
+      // Most terminals surface Alt as either ``alt`` or ``meta``; accept
+      // both so the binding works across xterm-style and kitty-style
+      // protocols. Guard against ctrl/super bits so a chord like
+      // Ctrl+Alt+<key> or Cmd+Alt+<key> doesn't spuriously fire the
+      // alt binding.
+      //
+      // Bare Escape on nastech-ink can arrive as ``key.meta=true`` on some
+      // terminals, so a configured ``alt+escape`` must not match that shape;
+      // require an explicit alt bit for escape chords (Copilot round-7
+      // follow-up on #19835).
+      return (key.alt === true || (key.meta && key.escape !== true)) && !key.ctrl && key.super !== true
+    case 'ctrl':
+      // Require the Ctrl bit AND a clear Alt/Super so a chord like
+      // Ctrl+Alt+<key> / Ctrl+Cmd+<key> doesn't spuriously match
+      // ``ctrl+<key>`` (Copilot round-6 review on #19835).
+      //
+      // The documented default (``ctrl+b``) additionally accepts the
+      // explicit ``key.super`` bit on macOS for Cmd+B muscle memory —
+      // but ONLY ``key.super`` (kitty-style), never ``key.meta``, since
+      // ``key.meta`` is nastech-ink's Alt signal and accepting it would
+      // fire the binding on Alt+B.
+      if (key.ctrl) {
+        return !key.alt && !key.meta && key.super !== true
+      }
+
+      return _isDefaultVoiceKey(configured) && isMac && key.super === true && !key.alt && !key.meta
+    case 'super':
+      // Require the explicit ``key.super`` bit (kitty-style protocol)
+      // AND clear Ctrl/Alt/Meta so Ctrl+Cmd+X or Alt+Cmd+X don't
+      // spuriously fire the super binding (Copilot round-6 review on
+      // #19835). Legacy-terminal users whose Cmd arrives as
+      // ``key.meta`` need a kitty-protocol terminal — see the
+      // _MOD_ALIASES doc-comment for the rationale.
+      return key.super === true && !key.ctrl && !key.alt && !key.meta
+  }
+}

package/src/lib/precisionWheel.ts

@@ -0,0 +1,48 @@
+const PRECISION_WHEEL_FRAME_MS = 16
+const PRECISION_WHEEL_STICKY_MS = 80
+
+export type PrecisionWheelState = {
+  active: boolean
+  dir: 0 | -1 | 1
+  lastEventAtMs: number
+  lastScrollAtMs: number
+}
+
+export type PrecisionWheelStep = {
+  active: boolean
+  entered: boolean
+  rows: 0 | 1
+}
+
+export function initPrecisionWheel(): PrecisionWheelState {
+  return { active: false, dir: 0, lastEventAtMs: 0, lastScrollAtMs: 0 }
+}
+
+export function computePrecisionWheelStep(
+  state: PrecisionWheelState,
+  dir: -1 | 1,
+  hasModifier: boolean,
+  now: number
+): PrecisionWheelStep {
+  const active = hasModifier || now - state.lastEventAtMs < PRECISION_WHEEL_STICKY_MS
+
+  if (!active) {
+    state.active = false
+
+    return { active: false, entered: false, rows: 0 }
+  }
+
+  const entered = !state.active
+
+  state.active = true
+  state.lastEventAtMs = now
+
+  if (dir === state.dir && now - state.lastScrollAtMs < PRECISION_WHEEL_FRAME_MS) {
+    return { active: true, entered, rows: 0 }
+  }
+
+  state.dir = dir
+  state.lastScrollAtMs = now
+
+  return { active: true, entered, rows: 1 }
+}

package/src/lib/prompt.ts

@@ -0,0 +1,35 @@
+const TERMUX_SAFE_PROMPT = '>'
+
+export function composerPromptText(
+  prompt: string,
+  profileName?: null | string,
+  shellMode = false,
+  termuxMode = false,
+  totalCols?: number
+): string {
+  if (shellMode) {
+    return '$'
+  }
+
+  if (termuxMode) {
+    // Termux fonts/terminal backends can render decorative prompt glyphs with
+    // ambiguous width; keep the live composer marker strictly single-cell ASCII
+    // so we never leave stale arrow artifacts while typing.
+    const basePrompt = TERMUX_SAFE_PROMPT
+
+    // On very wide panes we can still include profile context. On narrow/mobile
+    // panes this burns precious columns and increases wrap/clipping risk.
+    const wideEnoughForProfile = typeof totalCols === 'number' ? totalCols >= 90 : false
+    if (wideEnoughForProfile && profileName && !['default', 'custom'].includes(profileName)) {
+      return `${profileName} ${basePrompt}`
+    }
+
+    return basePrompt
+  }
+
+  if (profileName && !['default', 'custom'].includes(profileName)) {
+    return `${profileName} ${prompt}`
+  }
+
+  return prompt
+}

package/src/lib/reasoning.ts

@@ -0,0 +1,55 @@
+const TAGS = ['think', 'reasoning', 'thinking', 'thought', 'REASONING_SCRATCHPAD'] as const
+
+export interface SplitReasoning {
+  reasoning: string
+  text: string
+}
+
+export function splitReasoning(input: string): SplitReasoning {
+  let text = input
+  const reasoning: string[] = []
+
+  for (const tag of TAGS) {
+    const paired = new RegExp(`<${tag}>([\\s\\S]*?)</${tag}>\\s*`, 'gi')
+    text = text.replace(paired, (_m, inner: string) => {
+      const trimmed = inner.trim()
+
+      if (trimmed) {
+        reasoning.push(trimmed)
+      }
+
+      return ''
+    })
+
+    // Anchor to start-of-input so a literal `<think>` mid-prose (model quoting
+    // the word, code blocks containing the tag, etc.) doesn't eat every
+    // paragraph after it. Real unclosed reasoning blocks always lead the
+    // message — that's how reasoning models stream. See test
+    // "does not strip trailing prose after a stray mid-text <think> mention".
+    const unclosed = new RegExp(`^\\s*<${tag}>([\\s\\S]*)$`, 'i')
+    text = text.replace(unclosed, (_m, inner: string) => {
+      const trimmed = inner.trim()
+
+      if (trimmed) {
+        reasoning.push(trimmed)
+      }
+
+      return ''
+    })
+  }
+
+  return {
+    reasoning: reasoning.join('\n\n').trim(),
+    text: text.trim()
+  }
+}
+
+export const hasReasoningTag = (input: string) => {
+  for (const tag of TAGS) {
+    if (input.includes(`<${tag}>`)) {
+      return true
+    }
+  }
+
+  return false
+}

package/src/lib/rpc.ts

@@ -0,0 +1,41 @@
+import type { CommandDispatchResponse } from '../gatewayTypes.js'
+
+export type RpcResult = Record<string, any>
+
+export const asRpcResult = <T extends RpcResult = RpcResult>(value: unknown): T | null =>
+  !value || typeof value !== 'object' || Array.isArray(value) ? null : (value as T)
+
+export const asCommandDispatch = (value: unknown): CommandDispatchResponse | null => {
+  const o = asRpcResult(value)
+
+  if (!o || typeof o.type !== 'string') {
+    return null
+  }
+
+  const t = o.type
+
+  if (t === 'exec' || t === 'plugin') {
+    return { type: t, output: typeof o.output === 'string' ? o.output : undefined }
+  }
+
+  if (t === 'alias' && typeof o.target === 'string') {
+    return { type: 'alias', target: o.target }
+  }
+
+  if (t === 'skill' && typeof o.name === 'string') {
+    return { type: 'skill', name: o.name, message: typeof o.message === 'string' ? o.message : undefined }
+  }
+
+  if (t === 'send' && typeof o.message === 'string') {
+    return {
+      type: 'send',
+      message: o.message,
+      notice: typeof o.notice === 'string' ? o.notice : undefined,
+    }
+  }
+
+  return null
+}
+
+export const rpcErrorMessage = (err: unknown) =>
+  err instanceof Error && err.message ? err.message : typeof err === 'string' && err.trim() ? err : 'request failed'