Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

17.3 KB
Raw Blame
/**
 * Does Claude Code's own UI own the keyboard right now? Read from the pane's SCREEN, because the
 * dialogs that matter here fire no hook: the folder-trust prompt, `/model`, one-time setup questions.
 * The agent state keeps reading idle (or working) while one is up, so the ⌘M chat view would type into
 * it — the text is swallowed and the Enter answers the dialog. On the trust prompt the highlighted
 * default is "No, exit".
 *
 * MEASURED on Claude Code 2.1.283 (fullscreen TUI, which nodeterm enables):
 * - At its prompt — idle, or working with the queue open — the bottom of the screen is the input
 *   box: a `────` rule, a line starting `❯ ` at column 0 (continuation lines under it), another rule,
 *   then the status lines. In shell mode (a draft starting `!`) the prompt character is `!` instead
 *   (2.1.284; `#`, `&` and `@` drafts keep `❯`).
 * - The trust prompt and the `/model` picker REPLACE that box, and end in a key-hint footer
 *   ("Enter to confirm · Esc to cancel", "… · s to use this session only · Esc to cancel").
 * - A setup dialog seen in the field took the Enter while the typed text landed in the input box, so
 *   a dialog can also sit ABOVE a visible box. The footer alone is therefore enough to say "dialog".
 *
 * Only the BOTTOM of the capture is read: callers capture ~200 lines, history included, and a CLI
 * not in fullscreen mode leaves old dialogs and old input boxes in that history. The live box must
 * end within `BOX_TAIL_LINES` of the bottom, and a footer counts only in the last `FOOTER_TAIL_LINES`
 * lines, or at most `FOOTER_ABOVE_BOX_LINES` above the box — never further up the history.
 *
 * Only `prompt` means "safe to type". `unknown` (nothing readable) is left to the caller; a screen
 * with text but no input box and no footer is `no-prompt` — not necessarily a dialog (the CLI may be
 * starting, or gone and a shell owns the pane), but still no place to type a prompt.
 */
export type ClaudeScreen =
  | { kind: 'prompt' }
  | { kind: 'dialog'; text: string }
  | { kind: 'no-prompt' }
  | { kind: 'unknown' }

// eslint-disable-next-line no-control-regex
const ANSI = /\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g

/** A full-width rule of the input box (`─`, U+2500). */
const isRule = (line: string): boolean => /^─{20,}/.test(line.trim())
/** Any border a dialog is drawn under: the rule, or the `▔` top edge the `/model` picker uses. A
 *  label or notice can be painted over part of it (measured: "● high · /effort", a tmux notice),
 *  so it only has to START or END with the border characters. */
const isBorder = (line: string): boolean => /^\s*[─▔]{3,}/.test(line) || /[─▔]$/.test(line)
/** A key-hint footer. Capitalized on purpose: the working spinner says "esc to interrupt". */
const isFooter = (line: string): boolean => {
  const t = line.trim()
  return /^Enter to confirm\b/.test(t) || /(?:^|\s·\s)Esc to (?:cancel|exit|go back)$/.test(t)
}

/** Non-blank lines allowed under the box's bottom rule — the status lines (a custom statusline can
 *  take several). The agent list below them does not count (`isAgentListLine`). */
const BOX_TAIL_LINES = 8
/** At most this many agent-list lines are skipped, so an old box far up the history still is not
 *  taken for the live one. */
const AGENT_LIST_MAX_LINES = 40

/**
 * A line of the agent list Claude Code draws UNDER its status lines while background agents or
 * teammates run (MEASURED on 2.1.319, field screenshot + binary): one row per agent, starting with its
 * status dot — `● main` for the one in view, `○ <name>  <task>  <state>` for the rest — and, when the
 * list is longer than the space it gets, an overflow line `↓ 3 more` (`↑ 2 more · ↓ 3 more` once
 * scrolled). With a few agents it pushed the input box past `BOX_TAIL_LINES` and the ⌘M view read the
 * screen as having no input box.
 */
const isAgentListLine = (line: string): boolean => {
  const t = line.trim()
  return /^[●○] \S/.test(t) || /^(?:↑ \d+ more(?: · ↓ \d+ more)?|↓ \d+ more)$/.test(t)
}
/** A footer with no box: a dialog's key hints are its last line (measured: trust prompt, /model). */
const FOOTER_TAIL_LINES = 3
/** A footer above a live box: a dialog drawn right on top of the input box. */
const FOOTER_ABOVE_BOX_LINES = 4

/** The input box's first line: the `❯` prompt, or `!` in shell mode — followed by a NO-BREAK SPACE
 *  (U+00A0) there, measured, which `\s` covers. */
const isPromptLine = (line: string | undefined): boolean =>
  line !== undefined && (line.startsWith('❯') || /^!(\s|$)/.test(line))

/** Indexes of the non-blank lines, bottom first. */
const nonBlankFromBottom = (lines: readonly string[]): number[] =>
  lines.flatMap((l, i) => (l.trim() === '' ? [] : [i])).reverse()

/** The live input box: `[top rule, bottom rule]` line indexes, or null. */
function inputBox(lines: readonly string[]): [number, number] | null {
  // The bottom lines a box may end on: the first BOX_TAIL_LINES + 1 non-blank lines from the bottom,
  // not counting the agent list's lines (up to AGENT_LIST_MAX_LINES of them).
  const tail: number[] = []
  let listLines = 0
  for (const i of nonBlankFromBottom(lines)) {
    if (tail.length > BOX_TAIL_LINES) break
    if (isAgentListLine(lines[i]) && listLines < AGENT_LIST_MAX_LINES) {
      listLines++
      continue
    }
    tail.push(i)
  }
  for (const bottom of tail) {
    if (bottom === 0 || !isRule(lines[bottom])) continue
    for (let top = bottom - 1; top >= 0 && bottom - top <= 40; top--) {
      if (!isRule(lines[top])) continue
      return isPromptLine(lines[top + 1]) && top + 1 < bottom ? [top, bottom] : null
    }
    return null
  }
  return null
}

/** The dialog's own lines: from the border above the footer down to the footer, dedented. */
function dialogText(lines: readonly string[], footer: number): string {
  let start = footer
  while (start > 0 && footer - start < 30 && !isBorder(lines[start - 1])) start--
  const body = lines.slice(start, footer + 1).filter((l) => l.trim() !== '')
  const indent = Math.min(...body.map((l) => l.length - l.trimStart().length))
  return body.map((l) => l.slice(indent)).join('\n')
}

export function readClaudeScreen(screen: string): ClaudeScreen {
  const lines = screen.replace(ANSI, '').split(/\r?\n/).map((l) => l.trimEnd())
  if (lines.every((l) => l === '')) return { kind: 'unknown' }
  const box = inputBox(lines)
  const bottom = nonBlankFromBottom(lines)
  // Where a footer may be: under the box (or at the very bottom when there is no box), and right
  // above the box. Never inside it — a footer there is the user's own draft.
  const candidates = box
    ? [
        ...bottom.filter((i) => i > box[1]),
        ...bottom.filter((i) => i < box[0]).slice(0, FOOTER_ABOVE_BOX_LINES)
      ]
    : bottom.slice(0, FOOTER_TAIL_LINES)
  const footer = candidates.find((i) => isFooter(lines[i]))
  if (footer !== undefined) return { kind: 'dialog', text: dialogText(lines, footer) }
  return box ? { kind: 'prompt' } : { kind: 'no-prompt' }
}

/** What the ⌘M chat view's screen poll learns from one read of the pane (`pty.readChatScreen`): who
 *  owns the keyboard, and the suggested next prompt, if any. */
export interface ChatScreenRead {
  screen: ClaudeScreen
  suggestion: string | null
}

/** Refuse to type: anything but a visible input box, except a screen we could not read at all. */
export function claudeScreenBlocksInput(s: ClaudeScreen): boolean {
  return s.kind === 'dialog' || s.kind === 'no-prompt'
}

/**
 * Is Claude Code's composer EMPTY right now? Read from a STYLED capture (`capture-pane -e`): the one
 * fact the plain text cannot carry is the placeholder. MEASURED on Claude Code 2.1.301 (fullscreen
 * TUI, fixtures in `__fixtures__/claude/composer-capture.json`): an empty composer reads
 * `❯ Try "fix typecheck errors"` with the suggestion drawn SGR 2 (dim); a typed draft is the same
 * line in the default style. Shell mode (`!`) is a draft even with a dim placeholder after it — the
 * mode itself was typed, and text sent there runs as a shell command. A multi-line draft fills the
 * lines under the prompt line.
 *
 * Exists for issue #1144: the context-link discovery note was pasted + Enter'd into a composer that
 * already held the user's half-typed text, and both were submitted as one prompt.
 *
 * - `empty` — a live input box whose prompt line holds nothing but dim text (or nothing at all).
 * - `draft` — anything typed into it.
 * - `no-prompt` — a dialog owns the keyboard, or no input box is on screen (see `readClaudeScreen`).
 * - `unknown` — nothing readable (a failed or empty capture).
 *
 * The error is asymmetric on purpose: only dim text counts as placeholder, so a capture that lost
 * its SGR (or a CLI that styles the placeholder differently) reads `draft` and the caller does NOT
 * type — the safe direction.
 */
export type ClaudeComposer = 'empty' | 'draft' | 'no-prompt' | 'unknown'

/** Does any visible, non-blank character of this styled line (from `from`, a plain-text column)
 *  sit outside SGR dim? */
function hasUndimmedText(styled: string, from: number): boolean {
  return undimmedText(styled, from).trim() !== ''
}

/** The characters of this styled line (from `from`, a plain-text column) drawn outside SGR dim, in
 *  order. Walks the SGR state; non-SGR escapes are skipped. */
function undimmedText(styled: string, from: number): string {
  let dim = false
  let col = 0
  let out = ''
  let i = 0
  while (i < styled.length) {
    if (styled[i] === '\x1b') {
      const csi = /^\x1b\[([0-?]*)([ -/]*)([@-~])/.exec(styled.slice(i))
      if (csi) {
        if (csi[3] === 'm') dim = applySgrDim(csi[1], dim)
        i += csi[0].length
        continue
      }
      // eslint-disable-next-line no-control-regex
      const osc = /^\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/.exec(styled.slice(i))
      i += osc ? osc[0].length : 1
      continue
    }
    const ch = String.fromCodePoint(styled.codePointAt(i)!)
    if (col >= from && !dim) out += ch
    col += ch.length
    i += ch.length
  }
  return out
}

/** The dim flag after one SGR sequence's parameters. Extended colours (`38;5;n`, `38;2;r;g;b`, and
 *  the 48/58 forms) consume their arguments, so the `2` in `38;2;…` is never read as dim. */
function applySgrDim(params: string, dim: boolean): boolean {
  const ps = params === '' ? ['0'] : params.split(/[;:]/)
  for (let k = 0; k < ps.length; k++) {
    const p = ps[k] === '' ? 0 : Number(ps[k])
    if (p === 38 || p === 48 || p === 58) {
      const mode = Number(ps[k + 1])
      k += mode === 5 ? 2 : mode === 2 ? 4 : 1
    } else if (p === 0 || p === 22) dim = false
    else if (p === 2) dim = true
  }
  return dim
}

export function readClaudeComposer(styledScreen: string): ClaudeComposer {
  const styled = styledScreen.split(/\r?\n/)
  const lines = styled.map((l) => l.replace(ANSI, '').trimEnd())
  if (lines.every((l) => l === '')) return 'unknown'
  if (readClaudeScreen(styledScreen).kind !== 'prompt') return 'no-prompt'
  const box = inputBox(lines)
  if (!box) return 'no-prompt'
  const promptAt = box[0] + 1
  const prompt = lines[promptAt]
  if (!prompt.startsWith('❯')) return 'draft'
  for (let i = promptAt + 1; i < box[1]; i++) if (lines[i].trim() !== '') return 'draft'
  return hasUndimmedText(styled[promptAt], 1) ? 'draft' : 'empty'
}

/**
 * What the user's draft in Claude Code's composer says, read from a STYLED capture, with all
 * whitespace removed: the undimmed text of every line in the live input box, minus the `❯` prompt
 * character. Shell mode's `!` is kept, since it was typed. The dim placeholder is not part of it, so
 * an empty composer reads `''`. null when there is no live input box to read (a dialog, no box, a
 * draft too tall for the box reader, an empty capture).
 *
 * Exists so the typed chat send can see that ITS text reached the composer. Counting the text across
 * the whole screen fails for a short answer: typing also clears the placeholder and shortens the
 * status line ("· ? for shortcuts · ← for agents" goes away), so the letter `a` typed in answer to a
 * multiple-choice question appeared once more in the box and once less elsewhere. The count never
 * rose, and the Enter was withheld with the text sitting in the box.
 *
 * Without SGR (a capture that lost it), the placeholder reads as draft text. Callers compare against
 * the draft read before typing, so that only costs a match when the placeholder ends the same way.
 */
export function readClaudeDraft(styledScreen: string): string | null {
  return readClaudeDraftBox(styledScreen)?.draft ?? null
}

/**
 * `readClaudeDraft` plus how many screen rows the input box shows. MEASURED on Claude Code 2.1.319:
 * a long line wraps onto several rows, and the box stops growing at about half the pane's height
 * (7 rows at 24, 15 at 40, 25 at 60) and scrolls, showing the end of the draft with the caret there.
 * So `draft` can be only the tail of what the box holds, and `rows` only what is on screen.
 */
export function readClaudeDraftBox(styledScreen: string): { draft: string; rows: number } | null {
  const styled = styledScreen.split(/\r?\n/)
  const lines = styled.map((l) => l.replace(ANSI, '').trimEnd())
  if (lines.every((l) => l === '')) return null
  if (readClaudeScreen(styledScreen).kind !== 'prompt') return null
  const box = inputBox(lines)
  if (!box) return null
  let draft = ''
  for (let i = box[0] + 1; i < box[1]; i++) {
    const from = i === box[0] + 1 && lines[i].startsWith('❯') ? 1 : 0
    draft += undimmedText(styled[i], from)
  }
  return { draft: draft.replace(/\s/g, ''), rows: box[1] - box[0] - 1 }
}

/**
 * Why a draft in Claude Code's input box cannot be read back EXACTLY (`readClaudeDraftLine`):
 * - `multi-line` — it takes more than one row. MEASURED (2.1.319): a line that wraps and a real
 *   newline (M-Enter) look the same, a second row indented two spaces, and the wrap drops the space
 *   at the break, so neither the newlines nor the spaces could be put back.
 * - `placeholder` — it holds a collapsed paste or image (`[Pasted text #1 +12 lines]`, `[Image #1]`):
 *   the screen shows the placeholder, not the text behind it.
 * - `not-prompt` — the row does not start with the ordinary `❯` prompt (shell mode's `!`, say).
 */
export type ClaudeDraftLineRefusal = 'multi-line' | 'placeholder' | 'not-prompt'

export type ClaudeDraftLine =
  | { kind: 'empty' }
  | { kind: 'line'; text: string }
  | { kind: 'refused'; reason: ClaudeDraftLineRefusal }

const DRAFT_PLACEHOLDER = /\[(?:Pasted text|Image) #\d+/

/**
 * The user's draft in Claude Code's input box, read from a STYLED capture, EXACTLY: only when it is
 * one row with the ordinary prompt and no collapsed paste, so the text can be handed to the ⌘M chat
 * composer as typed (the dim placeholder and any dim inline hint are not part of it; trailing spaces
 * are lost, as tmux trims them). null when there is no live input box to read.
 */
export function readClaudeDraftLine(styledScreen: string): ClaudeDraftLine | null {
  const composer = readClaudeComposer(styledScreen)
  if (composer === 'empty') return { kind: 'empty' }
  if (composer !== 'draft') return null
  const styled = styledScreen.split(/\r?\n/)
  const lines = styled.map((l) => l.replace(ANSI, '').trimEnd())
  const box = inputBox(lines)
  if (!box) return null
  const promptAt = box[0] + 1
  for (let i = promptAt + 1; i < box[1]; i++) {
    if (lines[i].trim() !== '') return { kind: 'refused', reason: 'multi-line' }
  }
  if (!lines[promptAt].startsWith('❯')) return { kind: 'refused', reason: 'not-prompt' }
  // The prompt is `❯` and one space; everything after it that is not dim is the draft.
  const text = undimmedText(styled[promptAt], 1).replace(/^[ \u00a0]/, '').trimEnd()
  if (text === '') return { kind: 'empty' }
  if (DRAFT_PLACEHOLDER.test(text)) return { kind: 'refused', reason: 'placeholder' }
  return { kind: 'line', text }
}

/**
 * The next prompt Claude Code suggests after a turn, read from a STYLED capture: the dim text on its
 * prompt line while the input box holds no draft. null when there is none to offer.
 *
 * MEASURED on Claude Code 2.1.318: a few seconds after a turn ends, and only when there is an
 * obvious next step, Claude draws a suggestion as plain dim text (`❯ run it in the background`);
 * pressing → in its TUI accepts it. Two other dim texts sit in the same place and are NOT
 * suggestions: the fresh-session tips, always `Try "…"`, and `Press up to edit queued messages`
 * while a turn runs with a message queued. Both are refused here.
 *
 * Only dim text counts, so a capture that lost its SGR reads as a draft (`readClaudeComposer`) and
 * offers nothing.
 */
export function readClaudeSuggestion(styledScreen: string): string | null {
  const styled = styledScreen.split(/\r?\n/)
  const lines = styled.map((l) => l.replace(ANSI, '').trimEnd())
  if (lines.every((l) => l === '')) return null
  if (readClaudeScreen(styledScreen).kind !== 'prompt') return null
  // `empty`: a `❯` prompt line holding only dim text, and nothing on the lines under it.
  if (readClaudeComposer(styledScreen) !== 'empty') return null
  const box = inputBox(lines)
  if (!box) return null
  const suggestion = lines[box[0] + 1].slice(1).trim()
  if (suggestion === '' || NOT_SUGGESTIONS.some((re) => re.test(suggestion))) return null
  return suggestion
}

/** Dim texts on the prompt line that Claude Code draws but does not suggest (see above). */
const NOT_SUGGESTIONS: readonly RegExp[] = [/^Try "/, /^Press up to edit queued messages$/]