Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

16.7 KB
Raw Blame
/**
 * What Claude Code's screen says (architecture §2.6), with every marker taken from a
 * verbatim capture of Claude Code 2.1.290 in a headless magmux pane
 * (`ai-docs/reports/mcp-magmux-panes/phase2-captures.md`, fixtures in
 * `test-fixtures/screens/`).
 *
 * The screen is never the turn oracle — the transcript is (D3). The screen decides boot
 * readiness, names the dialogs that block boot, recognises the choice dialogs a turn can
 * block on, and supplies the degraded-mode answer and error rows. Every rule below is a
 * CLOSED list: an unrecognised layout reads as "not a dialog" (stay RUNNING, an honest
 * unknown), never as `blocked` (R3-H1).
 */

import { locateBox } from "./box-locate.js";
import type { SpanRun } from "./contract.js";
import { type ScreenState, boxTopRow, isBoxRule } from "./screen-model.js";

export type NamedDialog = "onboarding" | "trust" | "bypass" | "api_key";

export type BootReading =
  | { kind: "repl" } // input box: rule / line starting "❯" / rule, nothing typed
  | { kind: "dialog"; name: NamedDialog; text: string }
  | { kind: "choice"; text: string } // unnamed blocking screen, no input box
  | { kind: "booting" };

/**
 * The named first-run dialogs. They only NAME a dialog; whether boot is blocked is
 * decided by "no input box". 2.1.290 draws all of them on the primary screen.
 */
export const NAMED_DIALOGS: ReadonlyArray<{ name: NamedDialog; marker: string }> = [
  { name: "onboarding", marker: "Choose the text style" },
  { name: "trust", marker: "Is this a project you created or one you trust" },
  { name: "bypass", marker: "running in Bypass Permissions mode" },
  // Not recaptured on 2.1.290 (needs a foreign route with ANTHROPIC_API_KEY set);
  // verbatim 2.1.287 text from research-scratch/run-empty-config5-claudish-foreign.txt.
  { name: "api_key", marker: "Detected a custom API key in your environment" },
];

export type ChoiceDialogKind = "permission" | "plan" | "question";

/**
 * The choice dialogs a RUNNING turn can block on (R3-H1's closed list). Each header is
 * verbatim from a 2.1.290 capture, and is matched against the dialog region flattened into
 * one string (`flatText`), so a header word-wrapped on a narrow pane still matches. None of them has a `No, and tell Claude …(esc)` row
 * any more: permission ends `3. No` / `Esc to cancel · Tab to amend`, plan approval has
 * no No row at all, AskUserQuestion ends `Enter to select · ↑/↓ to navigate · Esc to cancel`.
 */
export const CHOICE_DIALOGS: ReadonlyArray<{ kind: ChoiceDialogKind; header: RegExp }> = [
  { kind: "permission", header: /\bDo you want to proceed\?/ },
  {
    kind: "permission",
    // the file name is bounded so a flattened region never lets it span a whole dialog
    header: /\bDo you want to (create|make this edit to|overwrite|delete) .{1,300}?\?/,
  },
  { kind: "plan", header: /\bWould you like to proceed\?/ },
  { kind: "question", header: /Enter to select · ↑\/↓ to navigate/ },
];

/** A numbered option row, optionally under the `❯` cursor: `❯ 1. Yes`, `  2. Pear`. */
const NUMBERED_OPTION = /^\s*(❯\s*)?\d+\.\s+\S/;
const FIRST_OPTION = /^\s*(❯\s*)?1\.\s+\S/;

/** Footers of 2.1.290's selection dialogs (boot dialogs have no numbers). */
const SELECT_FOOTER = /Enter to (confirm|select)\b.*Esc to cancel/;

/**
 * The working row: glyph, a capitalised word ending in `…`, an optional `(…)`. On a narrow
 * pane the parenthesised tail can wrap, so a tail with no `)` on this row also matches.
 */
const WORKING_ROW = /^\s*[·✢✳✶✻✽*●∗]\s+[A-Z][\w'-]*…(\s+\((?:.*\)|[^)]*))?\s*$/;

/** Bullet of an assistant message block. */
const BULLET = /^⏺(\s|$)/;

/** Error rows. 2.1.290 renders an API error as a `⏺` row. */
const ERROR_ROW =
  /^⏺\s.*(API Error\b|Please run \/login|Not logged in|You've hit your|session limit)|^\s*⎿\s+API Error\b/;

/** Attribute bit magmux passes through for faint (placeholder / ghost text). */
export const ATTR_FAINT = 2;

export function screenText(s: ScreenState): string {
  const lines = [...s.lines];
  while (lines.length && !lines[lines.length - 1]?.trim()) lines.pop();
  return lines.join("\n");
}

/**
 * Rows joined with a space, whitespace runs collapsed: what a marker phrase is matched
 * against. Claude Code word-wraps dialog prose to the pane width and drops the space at
 * the wrap, so a phrase on one 160-column row can split across two at 80 columns.
 */
export function flatText(lines: readonly string[]): string {
  return lines.join(" ").replace(/\s+/g, " ").trim();
}

/** Whitespace removed. Typed text and echoes wrap at a space (not drawn) or mid-word. */
function squash(s: string): string {
  return s.replace(/\s+/g, "");
}

/**
 * How many leading characters of a typed line identify it on screen: `min(40, cols − 4)`,
 * compared with whitespace removed and across wrapped rows (`echoAt`, `boxStartsWith`).
 */
export function echoHeadLength(cols: number): number {
  return Math.max(1, Math.min(40, cols - 4));
}

export function echoHead(line: string, cols: number): string {
  return line.slice(0, echoHeadLength(cols));
}

/** Characters of `line` whose cell is NOT faint. Columns are code-point indexes. */
function visibleText(line: string, spans: readonly SpanRun[] | undefined): string {
  if (!spans?.length) return line;
  const chars = Array.from(line);
  for (const [col, len, , , attr] of spans) {
    if ((attr & ATTR_FAINT) === 0) continue;
    for (let c = col; c < col + len && c < chars.length; c++) chars[c] = " ";
  }
  return chars.join("");
}

export interface InputBox {
  top: number; // row of the top rule
  bottom: number; // row of the bottom rule
  text: string; // typed text, placeholder (faint) cells excluded, trimmed
  menuOpen: boolean;
  menuItem: string | null;
}

/**
 * The box holds a line starting with `head`. `box.text` joins its rows with `\n`, and a
 * long line wraps at a space Claude Code does not draw, so both sides lose their whitespace.
 */
export function boxStartsWith(box: InputBox, head: string): boolean {
  return squash(box.text).startsWith(squash(head));
}

/**
 * Row `i` is the echo of a submitted line starting with `head`: `❯ ` with an ASCII space
 * (the box prompt is `❯` + NO-BREAK SPACE, so the box itself never matches), followed by
 * its two-space continuation rows when the echo wraps, compared with whitespace removed.
 * At 120 columns a prompt whose third word is a long path echoes as `❯ Use the Write tool
 * to create the file` alone, the path on the next row (`size-120x40-permission-…`).
 */
export function echoAt(lines: readonly string[], i: number, head: string): boolean {
  const first = lines[i] ?? "";
  if (!first.startsWith("❯ ")) return false;
  const want = squash(head);
  let got = squash(first.slice(2));
  for (let j = i + 1; got.length < want.length && j < lines.length; j++) {
    const row = lines[j] ?? "";
    if (!/^ {2}\S/.test(row)) break;
    got += squash(row);
  }
  return got.startsWith(want);
}

/** Some row is the echo of a submitted line starting with `head`. */
export function hasEcho(lines: readonly string[], head: string): boolean {
  for (let i = 0; i < lines.length; i++) if (echoAt(lines, i, head)) return true;
  return false;
}

const MENU_ROW = /^\s{2}❯ \/\S|^\s{4}\/\S|^\s{4}[*+] \S/;

/**
 * The REPL input box, or null when none is drawn. `text` is built from the box rows'
 * cells minus faint styling, so the fresh-boot placeholder (`❯ Try "how does <filepath>
 * work?"`, attr 2) reads as empty while typed text (no span) does not (X-M14).
 */
export function inputBox(s: ScreenState): InputBox | null {
  const top = boxTopRow(s.lines, s.cols);
  if (top < 0) return null;
  const bottom = boxBottomRow(s, top);
  if (bottom < 0) return null;
  return { top, bottom, text: boxText(s, top, bottom), ...menuAbove(s.lines, top) };
}

function boxBottomRow(s: ScreenState, top: number): number {
  for (let i = top + 1; i < s.lines.length && i <= top + 40; i++)
    if (isBoxRule(s.lines[i], s.cols)) return i;
  return -1;
}

/** The box prompt is `❯` + NO-BREAK SPACE; continuation rows are indented two spaces. */
function boxText(s: ScreenState, top: number, bottom: number): string {
  const parts: string[] = [];
  for (let i = top + 1; i < bottom; i++) {
    const raw = visibleText(s.lines[i] ?? "", s.spans[i]);
    const body = i === top + 1 ? raw.replace(/^❯\s?/, "") : raw.replace(/^ {2}/, "");
    parts.push(body.replace(/\s+$/, ""));
  }
  return parts.join("\n").trim();
}

/**
 * Menus (`/` commands, `@` files and agents) are drawn directly above the top rule. `top`
 * is the box's top rule row (from `inputBox` or `locateBox`).
 */
export function menuAbove(
  lines: readonly string[],
  top: number
): { menuOpen: boolean; menuItem: string | null } {
  let menuOpen = false;
  let menuItem: string | null = null;
  for (let i = top - 1; i >= 0 && i >= top - 12; i--) {
    const l = lines[i] ?? "";
    if (!l.trim()) break;
    if (!MENU_ROW.test(l)) continue;
    menuOpen = true;
    menuItem = l.match(/^\s{2}❯ (\S+)/)?.[1] ?? menuItem;
  }
  return { menuOpen, menuItem };
}

/** Index of the last `⏺` block row, or -1. */
function lastBulletRow(lines: readonly string[]): number {
  for (let i = lines.length - 1; i >= 0; i--) if (BULLET.test(lines[i] ?? "")) return i;
  return -1;
}

export interface ChoiceDialog {
  kind: ChoiceDialogKind;
  text: string;
}

/**
 * A choice dialog a turn is blocked on — the closed list of R3-H1. True only when ALL
 * hold: (a) a named header from CHOICE_DIALOGS is on screen, (b) no input box is drawn,
 * (c) a numbered `1.` option row sits below the last `⏺` block. Numbered prose with a
 * `No…` row above a running Bash fails (a) and (b); the working row fails all three.
 */
export function choiceDialog(s: ScreenState): ChoiceDialog | null {
  if (inputBox(s)) return null;
  const lines = s.lines;
  const start = lastBulletRow(lines) + 1;
  const below = lines.slice(start);
  const flat = flatText(below);
  const kind = CHOICE_DIALOGS.find((d) => d.header.test(flat))?.kind;
  if (!kind) return null;
  if (!below.some((l) => FIRST_OPTION.test(l))) return null;
  return { kind, text: below.filter((l) => l.trim()).join("\n") };
}

export function hasChoiceDialog(s: ScreenState): boolean {
  return choiceDialog(s) !== null;
}

/**
 * The words of the dialog magmux's input gate says is open: the non-empty rows below the
 * last `⏺` block (the whole screen at boot, where there is none). No header test and no box
 * test: the gate already decided a dialog is open, and only its text is read here
 * (architecture-v2 §6.3).
 */
export function dialogText(s: ScreenState): string {
  return s.lines
    .slice(lastBulletRow(s.lines) + 1)
    .filter((l) => l.trim())
    .join("\n");
}

/**
 * "Claude Code is working" — defence in depth only (never required by any rule, M20).
 * 2.1.290 shows no `esc to interrupt`; the working row is `✶ Simmering… (3s · ↓ 154 tokens)`,
 * and the finished row (`✻ Baked for 15s · done 12:08 PM`) has no `…`.
 */
export function isWorking(s: ScreenState): boolean {
  const top = boxTopRow(s.lines, s.cols);
  const region = top >= 0 ? s.lines.slice(0, top) : s.lines;
  return region.some((l) => WORKING_ROW.test(l));
}

/**
 * `isWorking` over the rows above the box located by the cursor (architecture-v2 §7.5);
 * null when no box is located, which settle corroboration reads as "no veto".
 */
export function workingAboveBox(s: ScreenState): boolean | null {
  const box = locateBox(s);
  return box ? s.lines.slice(0, box.top).some((l) => WORKING_ROW.test(l)) : null;
}

/** A Stop hook is running: `· Processing… (running Stop hook · 2s …)`. */
export function stopHookRunning(s: ScreenState): boolean {
  return s.lines.some((l) => /\(running Stop hook\b/.test(l));
}

export function transcriptSavingOff(s: ScreenState): boolean {
  return s.lines.some((l) => l.includes("Transcript saving is off"));
}

export function screenErrorRows(s: ScreenState): string[] {
  return s.lines.filter((l) => ERROR_ROW.test(l)).map((l) => l.trim());
}

function isToolHeader(lines: readonly string[], i: number): boolean {
  const l = lines[i] ?? "";
  if (/^⏺ [A-Z][A-Za-z0-9_:-]*\(/.test(l)) return true; // ⏺ Write(hello.txt), ⏺ Agent(fruit)
  if (/^⏺ Agent "[^"]*" (finished|failed)/.test(l)) return true;
  if (/^⏺ Background command /.test(l)) return true;
  if (/^⏺ User declined to answer questions/.test(l)) return true;
  // A Bash description row: the next non-empty row is its `⎿  $ command` row.
  for (let j = i + 1; j < lines.length && j <= i + 2; j++) {
    const n = lines[j] ?? "";
    if (!n.trim()) continue;
    return /^\s+⎿\s+\$ /.test(n);
  }
  return false;
}

const NON_ANSWER_ROW =
  /^\s+⎿|^\s{2}(Ran|Read|Searched|Wrote|Edited|Listed|Updated) \d+ |^\s*[·✢✳✶✻✽*●∗]\s|^\s*\(ctrl\+/;

/**
 * Degraded-mode answer (C4): the `⏺` prose rows after the LAST echo of `echo` and
 * their indented continuations, minus tool rows, sub-result rows (`  ⎿ …`), collapsed
 * tool summaries (`  Ran 1 shell command`), working/finished rows and error rows (L14).
 */
export function screenAnswer(s: ScreenState, echo: string): string {
  const lines = s.lines;
  const top = boxTopRow(lines, s.cols);
  const end = top >= 0 ? top : lines.length;
  const start = echoRow(lines, end, echoHead(echo, s.cols)) + 1;
  if (start <= 0) return "";
  const out: string[] = [];
  let inProse = false;
  for (let i = start; i < end; i++) {
    const row = answerRow(lines, i, inProse);
    inProse = row.inProse;
    if (row.text !== null) out.push(row.text);
  }
  return out.join("\n").trim();
}

/** The LAST echo row above `end` of a line starting with `head`, or -1. */
function echoRow(lines: readonly string[], end: number, head: string): number {
  const above = lines.slice(0, end);
  for (let i = end - 1; i >= 0; i--) if (echoAt(above, i, head)) return i;
  return -1;
}

/** One row of the degraded answer: its text (or null) and whether a prose block continues. */
function answerRow(
  lines: readonly string[],
  i: number,
  inProse: boolean
): { text: string | null; inProse: boolean } {
  const l = lines[i] ?? "";
  if (BULLET.test(l)) {
    const prose = !isToolHeader(lines, i) && !ERROR_ROW.test(l);
    return { text: prose ? l.replace(/^⏺\s?/, "") : null, inProse: prose };
  }
  if (!l.trim()) return { text: inProse ? "" : null, inProse };
  if (NON_ANSWER_ROW.test(l) || isToolHeader(lines, i)) return { text: null, inProse: false };
  if (inProse && /^ {2}/.test(l)) return { text: l.slice(2), inProse: true };
  return { text: null, inProse: false };
}

/**
 * The child's own `--agent` refusal. magmux's `exit.lastLine` truncates long lines
 * (`--agent 'zzz-not-real' not found. Avail…`, captured), so the agent list is optional
 * here; read the full line from the final screen when it is needed.
 */
export function agentRejectedLine(text: string): string | null {
  const m = text.match(/--agent '([^']+)' not found\.(?: Available agents:[^\n]*)?/);
  return m ? m[0] : null;
}

/** Matched against the flattened screen, so a marker wrapped on a narrow pane still names it. */
function namedDialog(flat: string): NamedDialog | null {
  for (const d of NAMED_DIALOGS) if (flat.includes(d.marker)) return d.name;
  return null;
}

/**
 * An unnamed static non-REPL screen with choice markers (M2). The footers are matched
 * against the flattened screen: at 40 columns the AskUserQuestion footer wraps as
 * `Enter to select · ↑/↓ to navigate · Esc` / `to cancel` (`size-40x24-ask-user-question`).
 */
function isUnnamedChoice(lines: readonly string[]): boolean {
  const numbered = lines.some((l) => NUMBERED_OPTION.test(l));
  const yesNo = lines.some((l) => /^\s*(❯\s*)?(\d+\.\s+)?(Yes|No)\b|\(esc\)/.test(l));
  if (numbered && yesNo) return true;
  const flat = flatText(lines);
  return /Press Enter to continue/.test(flat) || SELECT_FOOTER.test(flat);
}

/**
 * Names a screen that blocks boot, with no box test: whether boot is blocked is the input
 * gate's call (`input.ready` false, static), and this only says WHICH screen it is — a
 * named first-run dialog, an unnamed choice screen, or neither (architecture-v2 §6.2).
 */
export function nameBootScreen(s: ScreenState): Exclude<BootReading, { kind: "repl" }> {
  const named = namedDialog(flatText(s.lines));
  if (named) return { kind: "dialog", name: named, text: screenText(s) };
  if (isUnnamedChoice(s.lines)) return { kind: "choice", text: screenText(s) };
  return { kind: "booting" };
}

/**
 * Boot reading from the screen alone: alt and primary screens both read (2.1.290's dialogs
 * are on the primary one). PaneSession reads boot from magmux's input gate; this stays for
 * the boot canary and the fixture tests.
 */
export function readBoot(s: ScreenState): BootReading {
  const box = inputBox(s);
  const named = nameBootScreen(s);
  if (box && named.kind !== "dialog")
    return box.text === "" ? { kind: "repl" } : { kind: "booting" };
  return named;
}