Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

24.5 KB
Raw Blame
import type { AgentEngine } from '../types.js'
import type { PaneInspection, PaneTakeover } from '../facets/screen.js'

type Takeover = (capture: string, currentUi: string) => PaneTakeover | null
export function stripAnsi(value: string): string {
  return value.replace(/\u001b\[[0-9;:]*[A-Za-z]/g, '')
}

/**
 * The SGR attributes an escape sequence actually sets, with extended-colour arguments removed.
 *
 * `38`/`48`/`58` introduce a colour whose ARGUMENTS are numbers, not attributes: `5;<n>` for 256 and
 * `2;<r>;<g>;<b>` for truecolor. Without this skip a truecolor foreground (`38;2;…`) reads as SGR 2
 * — dim — and a line the user had typed would be mistaken for an empty composer, which is the one
 * direction this must never be wrong in: the pane would read idle and be respawned under a draft.
 */
function sgrAttributes(params: readonly string[]): string[] {
  const attributes: string[] = []
  for (let index = 0; index < params.length; index += 1) {
    const code = params[index]
    if (code !== '38' && code !== '48' && code !== '58') {
      attributes.push(code)
      continue
    }
    const kind = params[index + 1]
    index += kind === '5' ? 2 : kind === '2' ? 4 : 1
  }
  return attributes
}

/**
 * The background an SGR sequence sets, as a comparable string — or null if it sets none.
 *
 * Needed because a composer box is identified by the colour it PAINTS, and the parameters that
 * choose one are positional: `48;5;<n>` and `48;2;<r>;<g>;<b>` carry their arguments inline, so the
 * arguments have to be consumed rather than read as further attributes. `38`/`58` are skipped the
 * same way for the same reason — a truecolor FOREGROUND ends in numbers that would otherwise parse
 * as a background code of their own.
 *
 * SGR 0 counts: a reset puts the default background back, which is a change like any other.
 */
function sgrBackground(params: readonly string[]): string | null {
  for (let index = 0; index < params.length; index += 1) {
    const code = params[index]
    if (code === '48') {
      const kind = params[index + 1]
      return params.slice(index, index + (kind === '5' ? 3 : kind === '2' ? 5 : 2)).join(';')
    }
    if (code === '49' || /^(?:4[0-7]|10[0-7])$/.test(code)) return code
    if (code === '0' || code === '') return '49'
    if (code === '38' || code === '58') {
      const kind = params[index + 1]
      index += kind === '5' ? 2 : kind === '2' ? 4 : 1
    }
  }
  return null
}

/**
 * The span of a gutter line the BOX ITSELF paints — everything after the marker was wrong.
 *
 * A TUI draws one row of the terminal at a time, so anything floating OVER the composer lands on the
 * composer's own lines. OpenCode's `Getting started` card is exactly that: a panel on the right-hand
 * side, and its rows are written after the composer's on the same lines. Reading to end-of-line took
 * the card's text as something the user had typed —
 *
 *   ┃ <121 spaces of composer>  <sidebar>  Connect provider        /connect
 *
 * so `draft` was true over an EMPTY composer, the pane never read idle, and every model switch came
 * back AGENT_BUSY. Measured on a live pane (`harness-opencode-*`, 2026-09-15) with nothing typed in.
 * Fourth variant of the family above: the marker is found, the strip is dropped, and then the wrong
 * COLUMNS are read.
 *
 * The boundary is the box's own background. Everything a box paints is painted in it, so the
 * interior runs from the background set right after the marker to the next background change — in
 * the capture above, back to the pane's `48;2;10;10;10` where the box ends and the sidebar begins.
 *
 * Two deliberate conservatisms, both pointing the same way — a real draft must never be read as an
 * empty prompt, because that respawns the engine under text the user typed:
 *   * A background that appears only AFTER visible text is not the interior's. It is a highlight
 *     drawn mid-draft, and treating it as the boundary would cut the draft off at its own styling.
 *   * A line that sets no background at all is not clipped. Plain-text panes (and every engine that
 *     paints no box) keep the whole line, exactly as before.
 */
function gutterBoxInterior(line: string, markerIndex: number): string {
  const after = line.slice(markerIndex + 1)
  const sgr = /\u001b\[([0-9;:]*)m/g
  let interior: string | null = null
  let end = after.length
  let match: RegExpExecArray | null
  while ((match = sgr.exec(after)) !== null) {
    const background = sgrBackground(match[1].split(/[;:]/))
    if (background === null) continue
    if (interior === null) {
      if (stripAnsi(after.slice(0, match.index)).trim().length > 0) break
      interior = background
      continue
    }
    if (background !== interior) { end = match.index; break }
  }
  return after.slice(0, end)
}

/**
 * Is the text after the composer marker the PLACEHOLDER, rather than something the user typed?
 *
 * Read from the STYLING, never the words: the placeholder sentence differs per engine and changes
 * between versions, but every one of these TUIs greys its placeholder out somehow and none of them
 * styles a draft the same way.
 *
 * Two attributes, because two are in use. SGR 2 (dim) is what claude, codex and devin draw; SGR 3
 * (italic) is what hermes draws — its `Ask anything, or type / for commands…` is italic over a
 * 256-colour gold (`ESC[3m ESC[38;5;136m`) and carries no dim at all. Looking only for dim made
 * EVERY hermes pane look like a pane with a draft in it, so `idle` was false for the agent's whole
 * life and every retarget and model switch came back AGENT_BUSY over an engine sitting at an empty
 * prompt. Same failure the comment on `promptMarker` warns about, one step further along: the
 * marker was found, and then the placeholder was not recognised as one.
 */
function hasPlaceholderSgr(value: string): boolean {
  return [...value.matchAll(/\u001b\[([0-9;:]*)m/g)]
    .some((match) => {
      const attributes = sgrAttributes(match[1].split(/[;:]/))
      return attributes.includes('2') || attributes.includes('3')
    })
}

/**
 * Is this SGR foreground a MUTED one — the grey a TUI writes hints and placeholders in?
 *
 * Returns null when the sequence sets no foreground, so a caller can keep the colour already in
 * effect rather than treating "no change" as a change.
 *
 * Grey is judged by the colour itself: equal channels, and dark enough to read as secondary next to
 * the near-white a composer draws real text in. OpenCode 1.18's placeholder is `38;2;128;128;128`,
 * OpenCode 2's `38;2;180;180;180` (measured on 2.0.24: above the old 0xb0 bound, so a new harness read
 * as holding a draft and every model switch was AGENT_BUSY), and its own text `38;2;255;255;255`;
 * up to 0xc0 is still well short of that white. The 256-colour ramp (232–255) and SGR 90 are the
 * same intent spelled differently.
 */
function sgrMutedForeground(params: readonly string[]): boolean | null {
  for (let index = 0; index < params.length; index += 1) {
    const code = params[index]
    if (code === '38') {
      const kind = params[index + 1]
      if (kind === '2') {
        const [r, g, b] = [params[index + 2], params[index + 3], params[index + 4]].map(Number)
        if (![r, g, b].every(Number.isFinite)) return null
        return r === g && g === b && r >= 0x40 && r <= 0xc0
      }
      if (kind === '5') {
        const n = Number(params[index + 2])
        if (!Number.isFinite(n)) return null
        // 8 is bright black; 232–255 is the grey ramp, whose middle is the secondary tone.
        return n === 8 || (n >= 236 && n <= 250)
      }
      return null
    }
    if (code === '90') return true
    if (code === '39' || code === '0' || code === '') return false
    if (/^(?:3[0-7]|9[1-7])$/.test(code)) return false
    if (code === '48' || code === '58') {
      const kind = params[index + 1]
      index += kind === '5' ? 2 : kind === '2' ? 4 : 1
    }
  }
  return null
}

/**
 * Is EVERY visible character here written in a muted colour — i.e. is this a hint rather than a draft?
 *
 * The third placeholder styling this module has had to learn, after dim (claude, codex, devin) and
 * italic (hermes). OpenCode draws `Ask anything… "What is the tech stack of this project?"` as a plain
 * TRUECOLOR GREY with no dim and no italic attribute at all, so [hasPlaceholderSgr] saw nothing and a
 * brand-new pane read as a pane with a draft in it: never idle, and every model switch on an agent
 * with no messages yet refused as AGENT_BUSY over an empty composer. Measured on 1.18.31.
 *
 * ⚠️ EVERY character, not any — which is what keeps this from swallowing a real draft. A composer
 * writes what the user typed in its normal near-white; one such character anywhere means this is
 * text, whatever grey hint may be sitting beside it. Spaces are not evidence of either and carry no
 * colour worth reading, so they are skipped.
 */
function allVisibleTextIsMuted(value: string): boolean {
  const sgr = /\u001b\[([0-9;:]*)m/g
  let muted: boolean | null = null
  let cursor = 0
  let sawText = false
  let match: RegExpExecArray | null
  const segment = (text: string): boolean => {
    if (!text.trim()) return true
    sawText = true
    return muted === true
  }
  while ((match = sgr.exec(value)) !== null) {
    if (!segment(value.slice(cursor, match.index))) return false
    const next = sgrMutedForeground(match[1].split(/[;:]/))
    if (next !== null) muted = next
    cursor = match.index + match[0].length
  }
  if (!segment(value.slice(cursor))) return false
  return sawText
}

/**
 * The glyph each CLI puts in front of its composer. They do not share one: cursor uses `→`, devin `❭`
 * (U+276D — close to, but not, claude's `❯` U+276F), and pi draws no marker at all. Getting this wrong is
 * not cosmetic — with no prompt found the pane never reads idle, and every switch is refused as BUSY.
 */
function promptMarker(engine: AgentEngine): RegExp {
  if (engine === 'cursor') return /→/u
  if (engine === 'devin') return /[❭›❯]/u
  if (engine === 'opencode') return /┃/u
  return /[›❯]/u
}

/** One `─` may end it: Claude Code's top rule after `/rename` is `───…─── name ─` (claude/composer.ts, task #2428). */
const COMPOSER_RULE = /^[─━]{3,}(?:.*[─━])?\s*$/
/** A row only Claude Code's own footer draws: its shortcut hint, or its permission mode with the key that cycles it. Claude
 *  Code cuts the row at the pane's width, so its start is enough: a mode's `⏵⏵`/`⏸`, or `? for sh…`. A 42-column pane on
 *  DESKTOP-0TFH0OJ (2026-10-26) showed `⏵⏵ bypass permissions on (shift+tab to`, its composer read as absent, and every
 *  Swarm message typed into it was held before its Enter as `prompt_hidden`. After a long message is pasted, the footer is
 *  only `paste again to expand` (a real Buddy there, 2026-11-04). */
const CLAUDE_FOOTER = /^\s+(?:\? for sh|[⏵⏸]+\s|paste again|.*\(shift\+tab to cycle\))/
/**
 * The line of Claude Code's composer when it draws `>` for its marker, or -1. In the Harness terminal on Windows it draws
 * `>` and a no-break space where it draws `❯` elsewhere, so the pane never read idle and every Super Tab delivery to it
 * was held (DESKTOP-0TFH0OJ, 2026-10-23). Only the bottom box counts: `>` at the start of the line under its top rule,
 * and under its bottom rule Claude Code's own footer, with nothing but indented rows. A shell prompt (`PS C:\>`), or a
 * `>` quoted or framed in output above more output, indented or not, must never read as an idle Claude Code (review of
 * #1649). A box whose footer is not drawn reads as no composer: held, never typed into. Mac and Linux are unchanged.
 */
export function claudeWindowsComposer(lines: string[]): number {
  if (process.platform !== 'win32') return -1
  const visible = lines.map(stripAnsi)
  const bottom = visible.findLastIndex((line) => COMPOSER_RULE.test(line))
  const below = visible.slice(bottom + 1)
  if (bottom < 2 || below.some((line) => line.trim() && !/^\s/.test(line)) || !below.some((line) => CLAUDE_FOOTER.test(line))) return -1
  const top = visible.slice(0, bottom).findLastIndex((line) => COMPOSER_RULE.test(line))
  return top >= 0 && top + 1 < bottom && /^>(?:[\u00a0 ]|$)/.test(visible[top + 1]) ? top + 1 : -1
}

export function inspectPane(engine: AgentEngine, capture: string, takeover: Takeover = () => null, planPattern = /\bplan mode on\b/i): PaneInspection {
  if (engine === 'opencode') return inspectGutterBoxPane(capture, true)
  if (engine === 'copilot') return inspectGutterBoxPane(capture, false)
  if (engine === 'grok') return inspectGrokPane(capture)
  const rawLines = capture.split('\n')
  const boxed = engine === 'claude' ? claudeWindowsComposer(rawLines) : -1
  const promptIndex = Math.max(latestPromptLine(rawLines, promptMarker(engine)), boxed)
  // ANSI before a boxed `>` is not text, so the raw line is searched for the first `>`.
  const [marks, rawMarks] = promptIndex === boxed && boxed >= 0 ? [/^>/, />/] : [promptMarker(engine), promptMarker(engine)]
  const prompt = promptIndex >= 0 ? rawLines[promptIndex] : ''
  const currentUi = currentPaneUi(rawLines, promptIndex)
  const dialog = DIALOG_UI.test(currentUi) || takeover(capture, currentUi) !== null
  const plan = planPattern.test(currentUi)
  const marker = stripAnsi(prompt).search(marks)
  let visible = marker >= 0 ? stripAnsi(prompt).slice(marker + 1).replace(/\u00a0/g, ' ').trim() : ''
  const rawMarker = prompt.search(rawMarks)
  const rawTail = rawMarker >= 0 ? prompt.slice(rawMarker + 1) : ''
  // Devin 3000.11 greys its placeholder in truecolor, with no dim or italic: all of it muted, it is the placeholder.
  const placeholder = hasPlaceholderSgr(rawTail) || (engine === 'devin' && allVisibleTextIsMuted(rawTail))
  if (placeholder || IDE_CONTEXT_CHIPS.test(visible)) visible = ''
  const draft = visible.length > 0
  return { idle: !!prompt && !dialog && !draft, plan, dialog, draft }
}

/**
 * Claude Code shows what the connected IDE has open or selected as a chip in the empty composer, `❯ [⧉ In .env]` or
 * `❯ [⧉ Selected 3 lines from a.ts]`, in a colour of its own (not dim, not grey). It is context sent with the next
 * message, not text anyone typed. Read as a draft, an idle pane held every Super Tab delivery as
 * `team_waiting_draft`, and the same message was retried every second (2026-10-21, 10:44-10:49, 266 times).
 * ONLY chips and nothing else: any word typed beside one is a real draft and still holds.
 */
const IDE_CONTEXT_CHIPS = /^(?:\[⧉ [^\]]+\]\s*)+$/u

/** The latest composer prompt line; picker rows use the same glyphs, but numbered rows are not prompts. */
function latestPromptLine(rawLines: string[], marks: RegExp): number {
  return rawLines.findLastIndex((line) => {
    const visible = stripAnsi(line)
    const marker = visible.search(marks)
    return marker >= 0 && !/^\s*\d+\.\s/.test(visible.slice(marker + 1))
  })
}

/**
 * Old picker/plan text can remain in tmux history. Only UI below the latest prompt belongs to the
 * current interaction; if no prompt is visible, inspect the whole capture as a conservative fallback.
 */
function currentPaneUi(rawLines: string[], promptIndex: number): string {
  return stripAnsi((promptIndex >= 0 ? rawLines.slice(promptIndex) : rawLines).join('\n')).replace(/\u00a0/g, ' ')
}

export function paneModal(engine: AgentEngine, capture: string, readTakeover: Takeover = () => null): PaneTakeover | 'permission' | 'menu' | null {
  const rawLines = capture.split('\n')
  const currentUi = currentPaneUi(rawLines, latestPromptLine(rawLines, promptMarker(engine)))
  const takeover = readTakeover(capture, currentUi)
  if (takeover) return takeover
  // Below the prompt line: that line is the composer, or the echo of the last message, and either can
  // hold anything a person typed.
  if (PERMISSION_UI.test(currentUi.slice(currentUi.indexOf('\n') + 1))) return 'permission'
  return DIALOG_UI.test(currentUi.replace(/Starting MCP servers?/gi, '')) ? 'menu' : null
}

const DIALOG_UI = /Select Model(?: and Effort)?|Select Reasoning Level|Advanced Reasoning|(?<!between )Available models|Models matching|Edit Parameters|Type to filter.*Tab to edit|Esc to go back|Press enter to confirm|Do you want to proceed|Allow this action|permission required|Starting MCP servers?/i

/** The approval prompts among them. */
/**
 * An approval prompt's question. Claude Code asks "Do you want to proceed?", "Do you want to make this
 * edit to <file>?", "Do you want to allow Claude to fetch this content?", "Do you want to <verb> <target>?"
 * for the other tools, and "Would you like to proceed?" over a plan (2.1.289); Codex asks "Would you like
 * to run the following command?" and the like. The rows under it are read too (askQuestion.ts), but a
 * row wrapped in a narrow pane breaks that reading, and the question alone must still hold a message:
 * Enter approves the first row. Asked only below the prompt line, so never of what a person typed.
 */
const PERMISSION_UI = /\bDo you want to\b|\bWould you like to (?:proceed|run|make|apply|allow)\b|Allow this action|permission required/i

/** The rule a gutter-box composer is closed with: `╹▀▀▀▀…`. */
const GUTTER_BOX_RULE = /[─▀▁▔]{8,}/u

/**
 * A composer drawn as a BOX with a `┃` gutter — OpenCode's and Copilot's, which are the same shape.
 *
 * The generic reader cannot read either one. OpenCode's `┃` does not stop at the text: the last
 * gutter line is the box's own STATUS strip — `Build · <model> · <account>`, sitting directly on
 * the rule that closes the box — so taking the last line carrying the marker reads what the BOX says
 * about itself as something the user typed. Copilot fails one step earlier: its composer carries no
 * `›`/`❯` at all, while every message the user has ALREADY SENT is echoed into the transcript as
 * `❯ <text>` in full brightness, so the generic reader walks back to the last of those and reads a
 * sent message as a draft. Either way the pane was permanently "holding a draft": never idle, and
 * every retarget and model switch refused as AGENT_BUSY over an empty composer. Third variant of the
 * failure hermes had — there the placeholder was not recognised, here the wrong line is read.
 *
 * [hasStatusStrip] is the one thing that differs between the two, and it is OpenCode's alone. The
 * strip is identified by WHERE it is — the gutter line the closing rule sits under — rather than by
 * what it says, which is three variable fields that change with the model, the mode and the account.
 * When no rule follows, no strip is assumed and every gutter line counts as composer: a layout we do
 * not recognise must not silently swallow a line the user typed in. Copilot's box has no strip, so
 * its single gutter line IS the composer and dropping it would read a real draft as an empty prompt
 * — the one direction this must never be wrong in.
 *
 * Every gutter line is checked, not just the last: a long message wraps down the box, and reading
 * one line of it would call a full composer empty.
 *
 * A dialog needs no special case in either engine: both REPLACE the composer with the picker or the
 * permission prompt, so no gutter is on screen at all and the pane reads not-idle from the empty run
 * below rather than from [DIALOG_UI].
 */
function inspectGutterBoxPane(capture: string, hasStatusStrip: boolean): PaneInspection {
  const rawLines = capture.split('\n')
  const marks = /┃/u
  // The LAST contiguous run of gutter lines. Earlier runs are previous composers still in scrollback
  // — the message the user already sent is not a draft.
  const gutter: number[] = []
  for (let index = rawLines.length - 1; index >= 0; index -= 1) {
    if (marks.test(stripAnsi(rawLines[index]))) { gutter.unshift(index); continue }
    if (gutter.length > 0) break
  }
  if (gutter.length === 0) return { idle: false, plan: false, dialog: false, draft: false }
  const last = gutter[gutter.length - 1]
  const closed = last + 1 < rawLines.length && GUTTER_BOX_RULE.test(stripAnsi(rawLines[last + 1]))
  const composer = hasStatusStrip && closed ? gutter.slice(0, -1) : gutter
  const currentUi = stripAnsi(rawLines.slice(gutter[0]).join('\n')).replace(/\u00a0/g, ' ')
  const dialog = DIALOG_UI.test(currentUi)
  const draft = composer.some((index) => {
    const line = rawLines[index]
    const visibleMarker = stripAnsi(line).search(marks)
    if (visibleMarker < 0) return false
    const rawMarker = line.search(marks)
    // The box's interior, not the rest of the row: a panel floating over the composer writes into
    // these same lines, and its text is not a draft. See [gutterBoxInterior]. With no marker in the
    // RAW line there is no interior to bound — read the whole row, the direction that keeps a draft.
    const interior = rawMarker < 0
      ? stripAnsi(line).slice(visibleMarker + 1)
      : gutterBoxInterior(line, rawMarker)
    if (hasPlaceholderSgr(interior) || allVisibleTextIsMuted(interior)) return false
    return stripAnsi(interior).replace(/\u00a0/g, ' ').trim().length > 0
  })
  return { idle: !dialog && !draft, plan: /\bplan mode on\b/i.test(currentUi), dialog, draft }
}

/**
 * The context readout Pi's footer always carries — `0.0%/500k`, `1.5%/200k`. Present whether or not the
 * model advertises a thinking ladder, and drawn by the normal view alone, which is what makes it the
 * honest "the footer is on screen" signal. No `g` flag, so `test` carries no `lastIndex` between calls.
 */


/**
 * Grok draws its composer as a ROUNDED BOX, and the generic reader counts the box's own right edge
 * as something the user typed.
 *
 * Its empty composer is one line — `│ ❯` … padding … `│` — inside `╭─…─╮` above and
 * `╰─… Grok 4.6 (xhigh) ─╯` below. The shared reader takes everything after `❯`, strips ANSI, trims,
 * and finds `│`: one character, non-empty, so `draft` was true. Measured on a real pane
 * (`harness-grok-*`, 2026-09-09) with nothing typed into it: `visible after marker = "│"`, `draft =
 * true`, `idle = false`. Not a transient — the edge is drawn on every frame, so idle was false for
 * the agent's whole life and EVERY model switch came back AGENT_BUSY over an empty prompt. Same
 * family as the hermes and gutter-box bugs above; here the culprit is the box, not the placeholder.
 *
 * So the composer is the box's INTERIOR: the run of `│` body lines, read between their first and
 * last `│` rather than from the marker to end-of-line. Every body line is checked, not just the one
 * carrying `❯` — a long message wraps down the box and reading one line of it would call a full
 * composer empty.
 *
 * ⚠️ `│` is also Grok's footer separator (`Shift+Tab:mode │ Ctrl+x:shortcuts`), which sits BELOW the
 * box. It is excluded by requiring a body line to both open and close with `│`, which the footer —
 * one separator, no edges — never does.
 */
function inspectGrokPane(capture: string): PaneInspection {
  const rawLines = capture.split('\n')
  const visibleLines = rawLines.map((line) => stripAnsi(line).replace(/ /g, ' '))
  // The LAST box in the capture. Earlier ones are composers already sent, still in scrollback.
  const bottom = visibleLines.findLastIndex((line) => /^\s*╰[─╌]*.*╯\s*$/u.test(line))
  const top = bottom < 0
    ? -1
    : visibleLines.slice(0, bottom).findLastIndex((line) => /^\s*╭[─╌]+╮\s*$/u.test(line))
  // No recognisable box is "we cannot tell", which the caller reads as busy — the safe direction.
  // Respawning a pane whose layout we do not understand could discard a draft.
  if (top < 0 || bottom - top < 2) return { idle: false, plan: false, dialog: false, draft: false }
  const currentUi = visibleLines.slice(top).join('\n')
  const dialog = DIALOG_UI.test(currentUi)
  const draft = rawLines.slice(top + 1, bottom).some((line, offset) => {
    const visible = visibleLines[top + 1 + offset]
    const first = visible.indexOf('│')
    const last = visible.lastIndexOf('│')
    // Both edges, and not the same character: anything else is not a body line of this box.
    if (first < 0 || last <= first) return false
    const rawMarker = line.search(/[›❯]/u)
    if (rawMarker >= 0 && hasPlaceholderSgr(line.slice(rawMarker + 1))) return false
    // The marker is chrome, not content — it is printed whether or not anything was typed.
    return visible.slice(first + 1, last).replace(/[›❯]/u, '').trim().length > 0
  })
  return { idle: !dialog && !draft, plan: /\bplan mode on\b/i.test(currentUi), dialog, draft }
}

/**
 * Pi draws no composer marker, so idleness is read from its layout instead: the composer is the band
 * between the last two `───` rules, and the footer (`minimax/minimax-m3 • high`) is only rendered by the
 * normal view. A non-empty band is a draft the user is still typing — injecting there would splice a
 * slash command into their sentence.
 */