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.

feat(mobile): handle Codex async questions and key hints

tonyfe1238e1aef2
diff --git a/mobile/lib/phone/terminal_input_dock.dart b/mobile/lib/phone/terminal_input_dock.dart
index 9cf3b4d89..1be8df0ab 100644
--- a/mobile/lib/phone/terminal_input_dock.dart
+++ b/mobile/lib/phone/terminal_input_dock.dart
@@ -33,10 +33,15 @@ class TerminalInputDock extends StatefulWidget {
required this.onDismiss,
this.onPickImage,
this.onTakePhoto,
+ this.questionOpen = false,
});
final TerminalSession session;
+ /// An agent's question dialog is on the pane — see
+ /// [TerminalKeyBar.questionOpen].
+ final bool questionOpen;
+
/// The software keyboard is up, or has been asked for and is on its way.
final bool keyboardUp;
@@ -114,6 +119,7 @@ class _TerminalInputDockState extends State<TerminalInputDock>
onDismissKeyboard: widget.onDismiss,
onPickImage: widget.onPickImage,
onTakePhoto: widget.onTakePhoto,
+ questionOpen: widget.questionOpen,
),
),
builder: (context, child) {
diff --git a/mobile/lib/phone/terminal_key_bar.dart b/mobile/lib/phone/terminal_key_bar.dart
index b26df15e5..4d4b25d7d 100644
--- a/mobile/lib/phone/terminal_key_bar.dart
+++ b/mobile/lib/phone/terminal_key_bar.dart
@@ -30,6 +30,13 @@ import 'phone_sheet.dart';
///
/// Every key stays in the same place every time; this strip is used while
/// looking at the TERMINAL, not at the strip.
+///
+/// ⚠️ **One exception: `/` becomes `⏎` while an agent is asking something.**
+/// A question dialog is driven by the arrows and Enter, and Enter is the one
+/// the strip did not have — the keyboard's own `return` sends it, but nothing
+/// on screen says so, and on a dialog that reads "enter to submit answer" a
+/// strip of every other key it names reads as "Enter is missing". `/` is the
+/// slot to give up: a dialog has no prompt to start a command in.
class TerminalKeyBar extends StatelessWidget {
const TerminalKeyBar({
super.key,
@@ -40,10 +47,15 @@ class TerminalKeyBar extends StatelessWidget {
this.onPromptEdited,
this.onPickImage,
this.onTakePhoto,
+ this.questionOpen = false,
});
final Terminal terminal;
+ /// An agent's question dialog is on the pane: `/` gives its slot to `⏎` —
+ /// see the class docblock.
+ final bool questionOpen;
+
/// The `clear` key: empties the prompt being typed into. Null leaves the key
/// out.
final VoidCallback? onClearPrompt;
@@ -147,14 +159,25 @@ class TerminalKeyBar extends StatelessWidget {
onTap: () => terminal.keyInput(TerminalKey.arrowRight),
),
// Last before the rule, beside the image key: how a slash command
- // starts, and a phone keyboard buries `/` a layer down.
- _key(
- label: '/',
- onTap: () {
- terminal.textInput('/');
- onPromptEdited?.call();
- },
- ),
+ // starts, and a phone keyboard buries `/` a layer down. Enter in its
+ // place while a question is open — after the arrows, which is the order
+ // a dialog is answered in.
+ if (questionOpen)
+ _key(
+ icon: LucideIcons.cornerDownLeft300,
+ semanticLabel: 'Enter',
+ // Sent as the key, not as text: the keyboard's buffer holds nothing
+ // a dialog cares about, and Return is `\r` to every TUI here.
+ onTap: () => terminal.keyInput(TerminalKey.enter),
+ )
+ else
+ _key(
+ label: '/',
+ onTap: () {
+ terminal.textInput('/');
+ onPromptEdited?.call();
+ },
+ ),
];
// ⚠️ **Neither of these sends a byte anywhere**, and that is why they sit
// apart from the grid rather than in it. Every key to the left of the rule
diff --git a/mobile/lib/phone/terminal_page.dart b/mobile/lib/phone/terminal_page.dart
index 75d47654f..360e1813a 100644
--- a/mobile/lib/phone/terminal_page.dart
+++ b/mobile/lib/phone/terminal_page.dart
@@ -9,6 +9,8 @@ import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:image_picker/image_picker.dart';
import 'package:lucide_icons_flutter/lucide_icons.dart';
+// `TerminalStyle` — the key-hint chips wear the terminal's own face.
+import 'package:xterm/xterm.dart' show TerminalStyle;
import 'package:harness_mobile/core/models.dart' show Agent, AgentProject;
import 'package:harness_mobile/shared/theme/app_theme.dart';
@@ -18,6 +20,7 @@ import 'package:harness_mobile/terminal/image_transcode.dart';
import 'package:harness_mobile/terminal/terminal_font_store.dart';
import 'package:harness_mobile/terminal/terminal_theme.dart';
import 'package:harness_mobile/terminal/terminal_theme_store.dart';
+import 'package:harness_mobile/terminal/key_hints.dart';
import 'package:harness_mobile/terminal/question_pane.dart';
import 'package:harness_mobile/terminal/question_pane_watcher.dart';
import 'package:harness_mobile/terminal/terminal_session.dart';
@@ -459,6 +462,12 @@ class _TerminalPageState extends State<TerminalPage>
/// is new only when its text or its options differ.
String? _questionRaisedFor;
+ /// The queue of Codex async questions the keyboard was last raised for — see
+ /// [_onQuestionPane]. Once per change of the queue, for the reason
+ /// [_questionRaisedFor] is once per question: a keyboard put away while the
+ /// same questions wait stays away.
+ QueuedQuestions? _queueRaisedFor;
+
/// Point the question watcher at this page's current terminal.
///
/// Called from `build`, where both the engine and the session are known, and
@@ -497,6 +506,25 @@ class _TerminalPageState extends State<TerminalPage>
// again even if it words itself identically.
if (!open) _questionRaisedFor = null;
});
+ // A queued question — Codex's async kind — raises the keyboard too, once
+ // per change of the queue, by the same rule as a dialog below: the answer
+ // is typed, and the band's key and the chip are pressed, with it up. The
+ // header comes back with it, so the band is seen.
+ //
+ // ⚠️ **Marked only once the keyboard could actually be raised.** A queue
+ // read before the session takes input — a page opened onto an agent that
+ // already has one waiting — would otherwise be recorded as raised for, and
+ // nothing would try again until the queue changed.
+ final queued = _questionWatcher?.queued;
+ if (queued == null) {
+ _queueRaisedFor = null;
+ } else if (!open &&
+ queued != _queueRaisedFor &&
+ (_readFacts().session?.acceptsInput ?? false)) {
+ _queueRaisedFor = queued;
+ _chrome.reveal();
+ _raiseKeyboardForQuestion();
+ }
if (!open) return;
final key = view.fingerprint;
if (_questionRaisedFor == key) return;
@@ -534,6 +562,29 @@ class _TerminalPageState extends State<TerminalPage>
_armSettle();
}
+ /// The band's Answer: press the key Codex named for opening its queued
+ /// question, and bring the keyboard up for the answer.
+ ///
+ /// ⚠️ **The key the hint showed, not a Shift+Left of this page's own** — see
+ /// `KeyChord`. Once Codex opens the question it is an ordinary dialog on the
+ /// pane, and [_onQuestionPane] takes it from there.
+ void _answerQueuedQuestion() {
+ final queued = _questionWatcher?.queued;
+ final session = _readFacts().session;
+ if (queued == null || session == null || !session.acceptsInput) return;
+ if (!queued.answerKey.send(session.terminal)) return;
+ _raiseKeyboardForQuestion();
+ }
+
+ /// A key-hint chip: press the chord the pane's chrome named. Nothing else —
+ /// what the key does is the CLI's, and it redraws the screen to say so.
+ void _pressHint(KeyHint hint) {
+ final session = _readFacts().session;
+ if (session == null || !session.acceptsInput) return;
+ HapticFeedback.selectionClick();
+ hint.chord.send(session.terminal);
+ }
+
_PageFacts _readFacts() {
final notifier = widget.notifier;
final pane = notifier.panes
@@ -1146,6 +1197,29 @@ class _TerminalPageState extends State<TerminalPage>
!agentGone &&
session != null &&
(session.watching || session.status == TerminalSessionStatus.takenOver);
+ // Codex's queued async questions, for the band under the header. Only where
+ // the key can be pressed — not on a pane that cannot type, whose own band
+ // is up instead — and not once a question is open, when the dialog itself
+ // is what is on screen.
+ final queued = _questionWatcher?.queued;
+ final queuedBanner =
+ queued != null &&
+ !blocked &&
+ _reclaiming == null &&
+ (session?.acceptsInput ?? false) &&
+ _questionWatcher?.view == null
+ ? queued
+ : null;
+ // The keys the pane's chrome offers and a phone cannot press — see
+ // [parseKeyHints]. Not on a pane that cannot type.
+ //
+ // ⚠️ **The queued question's own key included, band or no band.** It was
+ // left out while the band was up, as the same press twice — and the chip
+ // is where the eye goes: beside `shift+← to answer` at the foot of the
+ // pane, where the band's button, up under the header, was not looked for.
+ final keyHints = agentGone || blocked || !(session?.acceptsInput ?? false)
+ ? const <KeyHint>[]
+ : _questionWatcher?.hints ?? const <KeyHint>[];
final takerName = phoneTakerName(
session,
(id) => widget.notifier.stateOf(id)?.machine.displayName,
@@ -1384,6 +1458,23 @@ class _TerminalPageState extends State<TerminalPage>
// says, the key bar is already under the thumb, and
// a column floating over the prompt being typed into
// would be in the way of both.
+ // The chrome's own keys as buttons — see
+ // [_KeyHintChips]. Laid OVER the pane, like the
+ // column below, so they come and go without
+ // resizing the terminal; and down at its foot,
+ // under the column, where the hints they stand
+ // for are drawn.
+ if (keyHints.isNotEmpty &&
+ session != null &&
+ session.hasRenderedFrame)
+ Positioned(
+ right: 8,
+ bottom: 6,
+ child: _KeyHintChips(
+ hints: keyHints,
+ onPress: _pressHint,
+ ),
+ ),
if (!_ownsInput)
Positioned(
right: TerminalActionColumn.inset,
@@ -1406,6 +1497,10 @@ class _TerminalPageState extends State<TerminalPage>
session: session,
keyboardUp: _keyBarUp,
onDismiss: _dismissInput,
+ // A dialog the watcher can read is open: the
+ // strip offers Enter for it. See
+ // [TerminalKeyBar.questionOpen].
+ questionOpen: _questionWatcher?.view != null,
// Only where the far side can actually take one: an
// older CLI never advertises the binary kind, so the
// upload would go nowhere silently. Null leaves the
@@ -1541,6 +1636,15 @@ class _TerminalPageState extends State<TerminalPage>
holderName: holderName,
onTakeControl: _takeControl,
),
+ // In the same place as that band, and for the same
+ // reason: it rides the header's slide rather than
+ // sitting on the output. Never both — see
+ // `queuedBanner`.
+ if (queuedBanner != null)
+ _QueuedQuestionBanner(
+ count: queuedBanner.count,
+ onAnswer: _answerQueuedQuestion,
+ ),
],
),
),
@@ -1935,6 +2039,212 @@ class _AgentGone extends StatelessWidget {
);
}
+/// Buttons for the keys the pane's chrome offers and a phone cannot press —
+/// `shift+tab cycle`, `ctrl+] skip`, `⌥+↓ main prompt` — each the key and the
+/// CLI's own word for what it does, both as the pane printed them and in the
+/// terminal's own face, so a chip reads as the hint it stands beside. See
+/// [parseKeyHints].
+///
+/// ⚠️ **Stacked in one column at the right edge, never side by side.** Laid in a
+/// row they ran across the pane's foot and covered the very lines they were
+/// read off — a wrapped footer's second line included. A column keeps to a
+/// strip at the edge, where a line of terminal text is usually shortest.
+///
+/// Nothing but the chips takes a touch: the column is as wide as its widest
+/// chip, and a Column hit-tests only its children, so the gaps between them
+/// let a tap through to the terminal.
+class _KeyHintChips extends StatelessWidget {
+ const _KeyHintChips({required this.hints, required this.onPress});
+
+ final List<KeyHint> hints;
+ final ValueChanged<KeyHint> onPress;
+
+ @override
+ Widget build(BuildContext context) {
+ AppTheme.watch(context);
+ // ⚠️ Out of the focus chain, as the key strip is: a chip that took focus on
+ // a tap would close the terminal's input connection, and the keyboard with
+ // it.
+ return ExcludeFocus(
+ child: MediaQuery.withNoTextScaling(
+ child: Column(
+ mainAxisSize: MainAxisSize.min,
+ crossAxisAlignment: CrossAxisAlignment.end,
+ children: [
+ for (var i = 0; i < hints.length; i++) ...[
+ if (i > 0) const SizedBox(height: 6),
+ _KeyHintChip(hint: hints[i], onTap: () => onPress(hints[i])),
+ ],
+ ],
+ ),
+ ),
+ );
+ }
+}
+
+class _KeyHintChip extends StatelessWidget {
+ const _KeyHintChip({required this.hint, required this.onTap});
+
+ final KeyHint hint;
+ final VoidCallback onTap;
+
+ @override
+ Widget build(BuildContext context) => Semantics(
+ button: true,
+ label: '${hint.action}, ${hint.keyText}',
+ child: GestureDetector(
+ behavior: HitTestBehavior.opaque,
+ onTap: onTap,
+ child: Container(
+ height: 28,
+ constraints: const BoxConstraints(maxWidth: 200),
+ padding: const EdgeInsets.symmetric(horizontal: 10),
+ decoration: BoxDecoration(
+ // Nearly opaque: it sits on terminal text, and a chip the output
+ // showed through would be read as more of the output.
+ color: AppPalette.panelBg.withValues(alpha: 0.94),
+ borderRadius: BorderRadius.circular(14),
+ border: Border.all(color: AppGlass.lift),
+ ),
+ // The terminal's face, followed live: Settings ▸ Terminal can change it
+ // while the chips are up.
+ child: ValueListenableBuilder<TerminalStyle>(
+ valueListenable: terminalFontStore,
+ builder: (context, face, _) => Row(
+ mainAxisSize: MainAxisSize.min,
+ children: [
+ Text(
+ hint.keyText,
+ style: TextStyle(
+ fontFamily: face.fontFamily,
+ fontFamilyFallback: face.fontFamilyFallback,
+ color: AppPalette.textPrimary,
+ fontSize: 12,
+ fontWeight: FontWeight.w600,
+ height: 1,
+ ),
+ ),
+ const SizedBox(width: 6),
+ Flexible(
+ child: Text(
+ hint.action,
+ maxLines: 1,
+ overflow: TextOverflow.ellipsis,
+ style: TextStyle(
+ fontFamily: face.fontFamily,
+ fontFamilyFallback: face.fontFamilyFallback,
+ color: AppPalette.textSecondary,
+ fontSize: 12,
+ height: 1,
+ ),
+ ),
+ ),
+ ],
+ ),
+ ),
+ ),
+ ),
+ );
+}
+
+/// Codex has asked something without stopping to wait — its async kind, queued
+/// under its composer as `? 1 question · shift+← to answer`.
+///
+/// ⚠️ **A band with a button, because the phone has no way to press the key
+/// the hint names.** The keyboard has no Shift or arrows, and the key strip has
+/// arrows without Shift, so the question sat there unanswerable until the agent
+/// gave up on it — Codex resolves an unanswered one on its own after a while.
+///
+/// Drawn like [_ControlBanner], in the same place, so the two read as one kind
+/// of thing: something about this terminal that needs a tap.
+class _QueuedQuestionBanner extends StatelessWidget {
+ const _QueuedQuestionBanner({required this.count, required this.onAnswer});
+
+ final int count;
+ final VoidCallback onAnswer;
+
+ @override
+ Widget build(BuildContext context) {
+ AppTheme.watch(context);
+ final ink = phoneToneColor(PhoneTone.attention);
+ return Semantics(
+ key: const ValueKey('phone-queued-question-strip'),
+ container: true,
+ liveRegion: true,
+ child: DecoratedBox(
+ decoration: BoxDecoration(
+ // Composited over the page's ground, as [_ControlBanner] is and for
+ // its reason: the terminal theme behind may be any colour.
+ color: Color.alphaBlend(
+ ink.withValues(alpha: 0.12),
+ AppPalette.windowBg,
+ ),
+ border: Border(
+ bottom: BorderSide(color: ink.withValues(alpha: 0.55)),
+ ),
+ ),
+ child: Padding(
+ padding: const EdgeInsets.fromLTRB(14, 10, 10, 10),
+ child: Row(
+ children: [
+ Icon(LucideIcons.messageCircleQuestion300, size: 15, color: ink),
+ const SizedBox(width: 10),
+ Expanded(
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ mainAxisSize: MainAxisSize.min,
+ children: [
+ Text(
+ count == 1
+ ? 'Codex is asking a question'
+ : 'Codex is asking $count questions',
+ maxLines: 1,
+ overflow: TextOverflow.ellipsis,
+ style: TextStyle(
+ color: AppPalette.textPrimary,
+ fontSize: 12,
+ fontWeight: FontWeight.w700,
+ ),
+ ),
+ const SizedBox(height: 2),
+ Text(
+ 'It keeps working while it waits for you.',
+ maxLines: 2,
+ overflow: TextOverflow.ellipsis,
+ style: TextStyle(
+ color: AppPalette.textSecondary,
+ fontSize: 11,
+ height: 1.3,
+ ),
+ ),
+ ],
+ ),
+ ),
+ const SizedBox(width: 10),
+ TextButton(
+ onPressed: onAnswer,
+ style: TextButton.styleFrom(
+ foregroundColor: ink,
+ padding: const EdgeInsets.symmetric(
+ horizontal: 12,
+ vertical: 8,
+ ),
+ minimumSize: Size.zero,
+ tapTargetSize: MaterialTapTargetSize.shrinkWrap,
+ ),
+ child: const Text(
+ 'Answer',
+ style: TextStyle(fontSize: 12, fontWeight: FontWeight.w600),
+ ),
+ ),
+ ],
+ ),
+ ),
+ ),
+ );
+ }
+}
+
/// The band over the output saying this pane cannot be typed into, and offering the way in.
///
/// ⚠️ **Over the output, not in the header.** The header's status word is 11pt in a corner beside
diff --git a/mobile/lib/terminal/key_chord.dart b/mobile/lib/terminal/key_chord.dart
new file mode 100644
index 000000000..2b617d0e2
--- /dev/null
+++ b/mobile/lib/terminal/key_chord.dart
@@ -0,0 +1,225 @@
+import 'package:xterm/xterm.dart';
+
+/// A key as a terminal program's own hint names it — `shift+←`, `ctrl+]`,
+/// `⌥+↓` — and what it takes to press it on [Terminal].
+///
+/// ⚠️ **Read off the hint, never assumed.** Codex's keymap is the person's to
+/// change (`tui.keymap` in its config), so the key a hint shows is the only one
+/// known to do what the hint says. A chord this cannot resolve is reported as
+/// null rather than guessed at: pressing the default on a remapped TUI sends a
+/// key that means something else there.
+class KeyChord {
+ const KeyChord._({
+ this.key,
+ this.char,
+ this.shift = false,
+ this.alt = false,
+ this.ctrl = false,
+ });
+
+ /// A named key — an arrow, Tab, a function key. Null when [char] is set.
+ final TerminalKey? key;
+
+ /// A single printable character, when the chord ends in one (`ctrl+]`).
+ final String? char;
+
+ final bool shift;
+ final bool alt;
+ final bool ctrl;
+
+ /// Held with a modifier — Shift, Alt or Ctrl.
+ bool get modified => shift || alt || ctrl;
+
+ /// Whether [send] has bytes for it. False only for a Ctrl chord on a
+ /// character outside the control range — there is nothing a terminal sends
+ /// for `ctrl+ä`, so a button for it would press nothing.
+ bool get sendable {
+ final char = this.char;
+ return key != null || !ctrl || (char != null && _controlCode(char) != null);
+ }
+
+ /// Parse the key part of a hint: `shift+←`, `shift + ←`, `⇧←`, `ctrl+]`.
+ ///
+ /// Null for anything this cannot press — an unknown key name, or a modifier a
+ /// terminal has no way to send (`cmd`, `⌘`).
+ static KeyChord? parse(String text) {
+ // The glyph modifiers are written straight onto their key (`⇧←`); give
+ // them the `+` the spelled-out ones carry, so both split the same way.
+ final spaced = text.trim().replaceAllMapped(
+ RegExp(r'([⇧⌃⌥])(?!\s*\+)'),
+ (m) => '${m[1]}+',
+ );
+ final parts = spaced
+ .split('+')
+ .map((part) => part.trim())
+ .toList(growable: false);
+ // `ctrl++` names the plus key itself: the split leaves it as two empties.
+ final keyName =
+ parts.length >= 3 &&
+ parts.last.isEmpty &&
+ parts[parts.length - 2].isEmpty
+ ? '+'
+ : parts.last;
+ final modifiers = parts.sublist(
+ 0,
+ keyName == '+' ? parts.length - 2 : parts.length - 1,
+ );
+ if (keyName.isEmpty) return null;
+ var shift = false;
+ var alt = false;
+ var ctrl = false;
+ for (final modifier in modifiers) {
+ switch (modifier.toLowerCase()) {
+ case 'shift' || '⇧':
+ shift = true;
+ case 'ctrl' || 'control' || 'ctl' || '⌃' || '^':
+ ctrl = true;
+ case 'alt' || 'option' || 'opt' || 'meta' || '⌥':
+ alt = true;
+ default:
+ // `cmd`/`⌘` and anything unrecognised: not a key a terminal sends.
+ return null;
+ }
+ }
+ final named = _namedKeys[keyName.toLowerCase()];
+ if (named != null) {
+ return KeyChord._(key: named, shift: shift, alt: alt, ctrl: ctrl);
+ }
+ // One character, pressed as itself. Anything longer is a key name this
+ // does not know.
+ if (keyName.runes.length != 1) return null;
+ return KeyChord._(
+ char: keyName.toLowerCase(),
+ shift: shift,
+ alt: alt,
+ ctrl: ctrl,
+ );
+ }
+
+ /// Press it: the bytes the far program reads for this chord.
+ ///
+ /// Returns false when nothing was sent — xterm has no sequence for that
+ /// combination of key and modifiers.
+ bool send(Terminal terminal) {
+ final key = this.key;
+ if (key != null) {
+ // ⚠️ **A navigation key with a modifier is written out, not looked up.**
+ // xterm's keytab answers these for a local terminal, not for a TUI on
+ // the far side: Shift+↑/↓ scroll this view and send nothing at all, and
+ // any other modifier on ↑/↓ comes out as Ctrl (`\E[1;5A`). The standard
+ // xterm form — `CSI 1 ; 1+mods final` — is what both CLIs read.
+ // Shift+← is the same bytes either way (`\E[1;2D`).
+ final csi = _modifiedNavigation[key];
+ if (csi != null && modified) {
+ final code = 1 + (shift ? 1 : 0) + (alt ? 2 : 0) + (ctrl ? 4 : 0);
+ terminal.textInput(csi(code));
+ return true;
+ }
+ return terminal.keyInput(key, shift: shift, alt: alt, ctrl: ctrl);
+ }
+ final char = this.char;
+ if (char == null) return false;
+ var out = char;
+ if (shift) out = out.toUpperCase();
+ if (ctrl) {
+ final code = _controlCode(char);
+ if (code == null) return false;
+ out = String.fromCharCode(code);
+ }
+ // ⚠️ Written out rather than left to `charInput`: the session's terminal
+ // is set up as macOS (see `terminal_session.dart`), and there xterm leaves
+ // Alt to the OS keyboard and sends nothing for it.
+ if (alt) out = '\x1b$out';
+ terminal.textInput(out);
+ return true;
+ }
+
+ /// The control byte for `ctrl` + [char]: letters, and `@ [ \ ] ^ _` —
+ /// the C0 range a control key reaches. Null for anything else.
+ static int? _controlCode(String char) {
+ final code = char.toUpperCase().codeUnitAt(0);
+ if (code >= 0x40 && code <= 0x5f) return code - 0x40;
+ if (char == ' ') return 0;
+ // What xterm and every terminal after it send for Ctrl+/: the same byte as
+ // Ctrl+_. Codex binds it (its side conversation).
+ if (char == '/') return 0x1f;
+ return null;
+ }
+
+ @override
+ bool operator ==(Object other) =>
+ other is KeyChord &&
+ other.key == key &&
+ other.char == char &&
+ other.shift == shift &&
+ other.alt == alt &&
+ other.ctrl == ctrl;
+
+ @override
+ int get hashCode => Object.hash(key, char, shift, alt, ctrl);
+
+ @override
+ String toString() => [
+ if (ctrl) 'ctrl',
+ if (alt) 'alt',
+ if (shift) 'shift',
+ key?.name ?? char ?? '?',
+ ].join('+');
+}
+
+/// The navigation keys whose modified forms [KeyChord.send] writes itself, by
+/// the xterm modifier code (`1 + shift + 2·alt + 4·ctrl`).
+final Map<TerminalKey, String Function(int)> _modifiedNavigation = {
+ TerminalKey.arrowUp: (m) => '\x1b[1;${m}A',
+ TerminalKey.arrowDown: (m) => '\x1b[1;${m}B',
+ TerminalKey.arrowRight: (m) => '\x1b[1;${m}C',
+ TerminalKey.arrowLeft: (m) => '\x1b[1;${m}D',
+ TerminalKey.home: (m) => '\x1b[1;${m}H',
+ TerminalKey.end: (m) => '\x1b[1;${m}F',
+ TerminalKey.pageUp: (m) => '\x1b[5;$m~',
+ TerminalKey.pageDown: (m) => '\x1b[6;$m~',
+ TerminalKey.delete: (m) => '\x1b[3;$m~',
+};
+
+/// The names a hint gives its keys, spelled out and as glyphs.
+const Map<String, TerminalKey> _namedKeys = {
+ '←': TerminalKey.arrowLeft,
+ 'left': TerminalKey.arrowLeft,
+ '→': TerminalKey.arrowRight,
+ 'right': TerminalKey.arrowRight,
+ '↑': TerminalKey.arrowUp,
+ 'up': TerminalKey.arrowUp,
+ '↓': TerminalKey.arrowDown,
+ 'down': TerminalKey.arrowDown,
+ 'tab': TerminalKey.tab,
+ '⇥': TerminalKey.tab,
+ 'enter': TerminalKey.enter,
+ 'return': TerminalKey.enter,
+ '⏎': TerminalKey.enter,
+ '↵': TerminalKey.enter,
+ 'esc': TerminalKey.escape,
+ 'escape': TerminalKey.escape,
+ 'space': TerminalKey.space,
+ 'backspace': TerminalKey.backspace,
+ '⌫': TerminalKey.backspace,
+ 'delete': TerminalKey.delete,
+ 'del': TerminalKey.delete,
+ 'home': TerminalKey.home,
+ 'end': TerminalKey.end,
+ 'pageup': TerminalKey.pageUp,
+ 'pgup': TerminalKey.pageUp,
+ 'pagedown': TerminalKey.pageDown,
+ 'pgdn': TerminalKey.pageDown,
+ 'f1': TerminalKey.f1,
+ 'f2': TerminalKey.f2,
+ 'f3': TerminalKey.f3,
+ 'f4': TerminalKey.f4,
+ 'f5': TerminalKey.f5,
+ 'f6': TerminalKey.f6,
+ 'f7': TerminalKey.f7,
+ 'f8': TerminalKey.f8,
+ 'f9': TerminalKey.f9,
+ 'f10': TerminalKey.f10,
+ 'f11': TerminalKey.f11,
+ 'f12': TerminalKey.f12,
+};
diff --git a/mobile/lib/terminal/key_hints.dart b/mobile/lib/terminal/key_hints.dart
new file mode 100644
index 000000000..896c422e9
--- /dev/null
+++ b/mobile/lib/terminal/key_hints.dart
@@ -0,0 +1,166 @@
+import 'package:xterm/xterm.dart';
+
+import 'key_chord.dart';
+
+/// A key a CLI's own chrome offers — `(shift+tab to cycle)`, `ctrl+] skip`,
+/// `⌥+↓ main prompt` — that a phone has no way to press.
+///
+/// ⚠️ **Why read them off the screen at all.** A phone keyboard has no Shift,
+/// Ctrl, Alt or function keys to hold, and the key strip carries only the
+/// handful of keys every pane needs. What each CLI binds to those modifiers is
+/// its own, changes between versions, and is the person's to remap (Codex's
+/// `tui.keymap`) — so the key the CLI prints next to what it does is the one
+/// reliable source for both halves. Measured on Codex 0.156.1 and Claude Code
+/// 2.1.281, where the chords that stranded a phone were `shift+←` (a queued
+/// question), `ctrl+]` and `⌥+↓` (leaving one), and `shift+tab` (Claude's
+/// permission modes).
+class KeyHint {
+ const KeyHint({
+ required this.chord,
+ required this.keyText,
+ required this.action,
+ });
+
+ final KeyChord chord;
+
+ /// The key as the chrome printed it — `ctrl+]`, `⌥+↓`, `shift + ←` — for the
+ /// button to repeat word for word, so it reads as the hint beside it rather
+ /// than as a translation of it.
+ final String keyText;
+
+ /// What the hint says the key does, as the CLI worded it — `cycle`,
+ /// `main prompt`.
+ final String action;
+
+ @override
+ bool operator ==(Object other) =>
+ other is KeyHint &&
+ other.chord == chord &&
+ other.keyText == keyText &&
+ other.action == action;
+
+ @override
+ int get hashCode => Object.hash(chord, keyText, action);
+
+ @override
+ String toString() => '$keyText $action';
+}
+
+/// How many of the pane's last non-blank lines count as its live chrome.
+///
+/// ⚠️ **Only the bottom, never the transcript.** Both CLIs draw their live
+/// chrome — the status line, a dialog's footer, the spinner's key hints —
+/// under everything else; what is above is conversation, where a model
+/// explaining a shortcut would otherwise grow a button. Five covers Claude's
+/// footer wrapped over three lines on a phone-width pane plus the status line.
+const int _chromeLines = 5;
+
+/// How far up from the bottom the walk may go looking for those lines.
+///
+/// ⚠️ A whole phone pane and more, not a handful: a short conversation leaves
+/// every row under its prompt blank, and on a 50-row pane that is most of the
+/// screen. Skipping a blank row costs nothing.
+const int _chromeScan = 60;
+
+/// The most hints offered at once. More would be a second key strip, and the
+/// point is the one or two a screen is actually asking for.
+const int _maxHints = 4;
+
+/// A key as the chrome writes one: modifiers joined to a key by `+`, or a bare
+/// function key. Modifiers are required for everything else — a plain `esc`
+/// or `tab` is a key the phone already has.
+final RegExp _chord = RegExp(
+ r'(?<![\w+])'
+ r'((?:(?:shift|ctrl|control|alt|option|opt|meta|[⇧⌃⌥])\s*\+\s*)+'
+ r"(?:tab|enter|return|esc|escape|space|backspace|delete|del|up|down|left|right|home|end|pageup|pagedown|pgup|pgdn|f(?:1[0-2]|[1-9])|[←→↑↓]|[a-z0-9]|[\]\[\\/.,;'`=\-])"
+ r'|f(?:1[0-2]|[1-9]))'
+ r'(?![\w])',
+ caseSensitive: false,
+);
+
+/// What follows a key: `to cycle`, `skip`, `main prompt` — words joined by
+/// single spaces, ended by the separators the chrome puts between hints
+/// (`·`, `|`, a bracket, a comma, a run of spaces) or by the line's end.
+final RegExp _action = RegExp(
+ r"^\s*(?:to\s+)?([a-z][a-z']*(?: [a-z][a-z']*){0,2})",
+ caseSensitive: false,
+);
+
+/// Chords never offered as a button, however the chrome describes them: the
+/// process-control keys. One tap from a glance must not be the key that quits
+/// the agent, drops its session or suspends it.
+bool _isProcessControl(KeyChord chord) =>
+ chord.ctrl &&
+ !chord.alt &&
+ !chord.shift &&
+ chord.key == null &&
+ const {'c', 'd', 'z', '\\'}.contains(chord.char);
+
+/// Words that make a hint an irreversible act. Offered as a button, each would
+/// be one tap from a glance at the screen — a confirm-by-pressing-again prompt
+/// (`ctrl+x again to delete`) exists precisely to take more than that.
+final RegExp _destructive = RegExp(
+ r'\b(exit|quit|kill|delete|discard|remove|suspend|abort|stop|uninstall|reset)\b',
+ caseSensitive: false,
+);
+
+/// Whether a phone can already press [chord] — the software keyboard or the
+/// key strip has it — so a hint for it would only repeat a key on screen.
+bool _phoneHas(KeyChord chord) {
+ if (chord.modified) return false;
+ final key = chord.key;
+ if (key == null) return true;
+ return const {
+ TerminalKey.escape,
+ TerminalKey.tab,
+ TerminalKey.enter,
+ TerminalKey.space,
+ TerminalKey.backspace,
+ TerminalKey.arrowLeft,
+ TerminalKey.arrowRight,
+ TerminalKey.arrowUp,
+ TerminalKey.arrowDown,
+ }.contains(key);
+}
+
+/// The hints in the pane's live chrome that a phone cannot press itself, in
+/// reading order, one per key.
+List<KeyHint> parseKeyHints(List<String> lines) {
+ final chrome = <String>[];
+ for (
+ var i = lines.length - 1;
+ i >= 0 && lines.length - i <= _chromeScan && chrome.length < _chromeLines;
+ i--
+ ) {
+ if (lines[i].trim().isNotEmpty) chrome.insert(0, lines[i]);
+ }
+ final hints = <KeyHint>[];
+ for (final line in chrome) {
+ for (final match in _chord.allMatches(line)) {
+ final chord = KeyChord.parse(match.group(1)!);
+ if (chord == null ||
+ !chord.sendable ||
+ _phoneHas(chord) ||
+ _isProcessControl(chord)) {
+ continue;
+ }
+ final words = _action.firstMatch(line.substring(match.end));
+ // A key with nothing said about it is a name in a sentence, not a hint.
+ if (words == null) continue;
+ final action = words.group(1)!.toLowerCase();
+ if (_destructive.hasMatch(action)) continue;
+ if (hints.any((hint) => hint.chord == chord)) continue;
+ hints.add(
+ KeyHint(
+ chord: chord,
+ // Spacing collapsed, nothing else touched: `shift + ←` stays as the
+ // pane drew it.
+ keyText: match.group(1)!.trim().replaceAll(RegExp(r'\s+'), ' '),
+ action: action,
+ ),
+ );
+ if (hints.length == _maxHints) return hints;
+ }
+ }
+ return hints;
+}
diff --git a/mobile/lib/terminal/question_pane.dart b/mobile/lib/terminal/question_pane.dart
index bed9c0ae6..165b6f76c 100644
--- a/mobile/lib/terminal/question_pane.dart
+++ b/mobile/lib/terminal/question_pane.dart
@@ -22,6 +22,8 @@ library;
import 'package:xterm/xterm.dart';
+import 'key_chord.dart';
+
/// Which CLI painted the dialog — the two this parser is verified against.
///
/// The engine matters for more than the frame: Codex highlights on a digit and
@@ -77,8 +79,8 @@ class QuestionPaneView {
final bool multi;
/// The footer says a digit only highlights and Enter commits — Codex's
- /// `request_user_input`. False where one digit selects and submits, which is
- /// every Claude dialog.
+ /// `request_user_input`. False where one digit selects and submits: every
+ /// Claude dialog, and Codex's async question (see [_asyncFooter]).
final bool enterSubmits;
/// The dialog is on screen but its top — the question and its first rows — is
@@ -128,6 +130,29 @@ final RegExp _enterSubmitsFooter = RegExp(
caseSensitive: false,
);
+/// The footer of a Codex ASYNC question once it has been opened out of the
+/// queue (`request_user_input_async`, see [parseQueuedQuestions]):
+/// `enter submit ctrl+] skip ⌥+↓ main prompt`.
+///
+/// ⚠️ **Not the synchronous dialog, and it does not behave like one.**
+/// Measured on Codex 0.156.1: a digit here selects AND submits — `2` answered
+/// "Green" on the spot — where the synchronous dialog's digit only moves the
+/// highlight. And the UI appends a free-text `Other` row of its own (the tool
+/// tells the model never to include one), which is an editor, not an answer.
+///
+/// Matched on the words, not the keys: `skip` and `main prompt` are what the
+/// hints do, and the keys in front of them are the person's to remap.
+final RegExp _asyncFooter = RegExp(
+ r'enter\s+submit\b.*\b(skip|main prompt)\b',
+ caseSensitive: false,
+);
+
+/// The free-text row an async question's UI adds under the model's options.
+final RegExp _asyncOtherRow = RegExp(
+ r'^other( \(write an answer\))?$',
+ caseSensitive: false,
+);
+
/// `❯ 1. Label` — with the caret optional and any checkbox peeled off.
final RegExp _row = RegExp(r'^\s*[❯›>]?\s*(\d+)\.\s+(.+?)\s*$');
@@ -155,13 +180,14 @@ final RegExp _ruleTop = RegExp(r'^[─━-]{6,}$');
final RegExp _codexDescription = RegExp(r'^(.+?)\s{2,}\S');
/// Codex's own chrome, drawn directly above a question with no blank line to
-/// separate it: the prompt caret, an event bullet, or the status line under the
-/// composer. Each marks the top of the dialog's frame.
+/// separate it: the prompt caret, an event bullet, the status line under the
+/// composer, or an async question's `1 of 2` counter. Each marks the top of the
+/// dialog's frame.
///
/// ⚠️ Without this the wrap walk had nothing to stop it — Codex paints no rule
/// and no tab bar — and it swallowed the whole transcript into the question.
final RegExp _codexChrome = RegExp(
- r'^\s*[›•❯>]|^\s*(Question \d+/\d+|Working \(|Ask Codex)',
+ r'^\s*[›•❯>]|^\s*(Question \d+/\d+|\d+ of \d+\s*$|Working \(|Ask Codex)',
);
/// Lines that may sit under a live dialog's footer without meaning the engine
@@ -216,8 +242,17 @@ final RegExp _outputGlyph = RegExp(
/// What a footer's continuation looks like: a `·` separator, or a phrase
/// naming a key and what it does.
+///
+/// ⚠️ **Every modifier a footer writes, glyphs included, and outside the word
+/// boundaries.** Codex's async question wraps its footer on a phone pane and,
+/// on its last question, the second line is `⌥+↓ prev question` alone — no
+/// `shift+`, no `ctrl+`, nothing this used to know. That line read as output
+/// under a dead dialog, the dialog was dropped, and the keyboard never came up
+/// for it. Measured on Codex 0.156.1, question 2 of 2. The modifiers sit before
+/// the `\b` group because a `\b` cannot follow `+` into `↓` or `]`: neither
+/// side is a word character.
final RegExp _footerHint = RegExp(
- r'\u00b7|\b(to (select|cancel|confirm|submit|toggle|navigate|edit|add|interrupt|view|expand)|esc|enter|tab|ctrl\+|shift\+|\u2191/\u2193|\u2190/\u2192)\b',
+ r'\u00b7|[⌥⌃⇧]\s*\+|\b(?:ctrl|shift|alt|option|opt|meta)\s*\+|\b(to (select|cancel|confirm|submit|toggle|navigate|edit|add|interrupt|view|expand)|esc|enter|tab|\u2191/\u2193|\u2190/\u2192)\b',
caseSensitive: false,
);
@@ -254,17 +289,20 @@ const int _maxWrapLines = 4;
/// lowest one. Reading upward from the bottom is what keeps an answered
/// question in the scrollback from being shown as an open one.
QuestionPaneView? readQuestionPane(Terminal terminal, QuestionEngine engine) {
- final lines = _visibleLines(terminal);
+ final lines = questionPaneLines(terminal);
if (lines.isEmpty) return null;
return parseQuestionLines(lines, engine);
}
-/// The buffer as plain text, oldest line first.
+/// The buffer as plain text, oldest line first — what every parser here reads.
+///
+/// Public so one read of the buffer can serve both [parseQuestionLines] and
+/// [parseQueuedQuestions] rather than each copying it out again.
///
/// ⚠️ **Reads the buffer, not the viewport.** Someone scrolled up to read
/// history is still being asked the question, and a pad that vanished when they
/// scrolled would be a pad that leaves exactly when it is being read about.
-List<String> _visibleLines(Terminal terminal) {
+List<String> questionPaneLines(Terminal terminal) {
final buffer = terminal.buffer;
final lines = buffer.lines;
final total = lines.length;
@@ -331,15 +369,26 @@ QuestionPaneView? parseQuestionLines(
}
}
- final enterSubmits = _enterSubmitsFooter.hasMatch(lines[footer]);
+ final asyncQuestion =
+ engine == QuestionEngine.codex && _asyncFooter.hasMatch(lines[footer]);
+ final enterSubmits =
+ !asyncQuestion && _enterSubmitsFooter.hasMatch(lines[footer]);
+ // The UI's own free-text row, always last — see [_asyncFooter]. Dropped here
+ // rather than folded into [_typeRow]: a Claude dialog's option CAN be called
+ // "Other", and there it is an answer.
+ if (asyncQuestion &&
+ rows.isNotEmpty &&
+ _asyncOtherRow.hasMatch(rows.last.label)) {
+ rows.removeLast();
+ }
// Rows in view but no "1." above them: the dialog's top is out of the buffer.
// Only Codex does this, and only its footer proves the dialog is still there.
- if (rows.isNotEmpty && start < 0 && enterSubmits) {
+ if (rows.isNotEmpty && start < 0 && (enterSubmits || asyncQuestion)) {
return QuestionPaneView(
question: '',
rows: rows,
multi: checkbox,
- enterSubmits: true,
+ enterSubmits: enterSubmits,
partial: true,
);
}
@@ -509,3 +558,125 @@ QuestionPaneRow? _parseRow(String line, QuestionEngine engine) {
checked: box != null && box.group(1)!.trim().isNotEmpty,
);
}
+
+/// Codex's async questions, waiting in its queue rather than open on screen.
+///
+/// ```
+/// • Queued follow-up inputs
+/// ? 1 question
+/// shift+← to answer
+///
+/// › Ask Codex to do anything
+/// ```
+///
+/// ⚠️ **Why a dialog parser cannot see this.** `request_user_input_async` asks
+/// and lets the agent carry on working: nothing is open, nothing has a footer
+/// or rows, and the composer stays live under it. The question only becomes a
+/// dialog once [answerKey] is pressed — and on a phone that key is one the
+/// keyboard does not have.
+class QueuedQuestions {
+ const QueuedQuestions({required this.count, required this.answerKey});
+
+ /// How many are waiting — `? 2 questions`.
+ final int count;
+
+ /// The key the hint says opens the first of them, as Codex names it — see
+ /// [KeyChord] for why it is read rather than assumed.
+ final KeyChord answerKey;
+
+ @override
+ bool operator ==(Object other) =>
+ other is QueuedQuestions &&
+ other.count == count &&
+ other.answerKey == answerKey;
+
+ @override
+ int get hashCode => Object.hash(count, answerKey);
+}
+
+/// `? 1 question` — the count line. Its wording varies with the count and, per
+/// the strings Codex 0.156.1 carries, may say `unanswered`.
+final RegExp _queuedCount = RegExp(
+ r'^\s*\?\s+(\d+)\s+(?:unanswered\s+)?questions?\s*$',
+ caseSensitive: false,
+);
+
+/// `shift+← to answer` — and `shift + ← to answer`, which is how the same hint
+/// was captured from another install: the key's spacing is not fixed.
+final RegExp _queuedHint = RegExp(
+ r'^\s*(\S(?:.*\S)?)\s+to answer\s*$',
+ caseSensitive: false,
+);
+
+/// Codex's composer line — `› Ask Codex to do anything`, or `›` over a draft.
+final RegExp _composer = RegExp(r'^\s*\u203a(\s|$)');
+
+/// How far above its hint the count line may sit. They are adjacent in every
+/// capture; one line of slack covers a repaint caught mid-way.
+const int _maxQueuedCountGap = 2;
+
+/// How far under the hint Codex's composer must be.
+///
+/// ⚠️ **The composer is what says the queue is live.** The block is part of
+/// Codex's bottom pane, always drawn right above the composer; one read with
+/// the hint and no composer under it is scrollback, or a Codex that has exited,
+/// and a button pressing a key into either would type into whatever is there
+/// now. The slack is for queued follow-up messages, which the same block can
+/// list under the question.
+const int _maxQueuedComposerScan = 10;
+
+/// Read Codex's queued async questions off the buffer, or null if none wait.
+///
+/// ⚠️ **Codex only, and only its live bottom pane.** Anchored to the LAST hint
+/// in the buffer, for the reason [readQuestionPane] anchors to the last
+/// footer, and only when Codex's composer is still drawn under it.
+QueuedQuestions? parseQueuedQuestions(List<String> lines) {
+ // ⚠️ **Every candidate from the bottom up, not just the last one.** A hint's
+ // shape — words, then `to answer` — is also the shape of a sentence, and the
+ // lowest such line can be the person's own draft in the composer. Each is
+ // checked in turn, and the first that is a real hint wins.
+ for (var at = lines.length - 1; at >= 0; at--) {
+ final match = _queuedHint.firstMatch(lines[at]);
+ if (match == null) continue;
+ final found = _queuedAt(lines, at, match.group(1)!);
+ if (found != null) return found;
+ }
+ return null;
+}
+
+/// The queue whose hint is on line [hintAt], naming [keyText] — or null when
+/// that line is not one.
+QueuedQuestions? _queuedAt(List<String> lines, int hintAt, String keyText) {
+ var count = 0;
+ for (var i = hintAt - 1; i >= 0 && hintAt - i <= _maxQueuedCountGap; i--) {
+ final match = _queuedCount.firstMatch(lines[i]);
+ if (match != null) {
+ count = int.parse(match.group(1)!);
+ break;
+ }
+ // Only blanks may stand between the two; anything else means this hint
+ // belongs to something other than a question count.
+ if (lines[i].trim().isNotEmpty) return null;
+ }
+ if (count <= 0) return null;
+
+ var live = false;
+ for (
+ var i = hintAt + 1;
+ i < lines.length && i - hintAt <= _maxQueuedComposerScan;
+ i++
+ ) {
+ if (_composer.hasMatch(lines[i])) {
+ live = true;
+ break;
+ }
+ // A dialog under the hint means the question has already been opened.
+ if (_footer.hasMatch(lines[i])) return null;
+ }
+ if (!live) return null;
+
+ final key = KeyChord.parse(keyText);
+ // A key this cannot press is no key at all — see [KeyChord].
+ if (key == null) return null;
+ return QueuedQuestions(count: count, answerKey: key);
+}
diff --git a/mobile/lib/terminal/question_pane_watcher.dart b/mobile/lib/terminal/question_pane_watcher.dart
index eb3a47715..f46698b66 100644
--- a/mobile/lib/terminal/question_pane_watcher.dart
+++ b/mobile/lib/terminal/question_pane_watcher.dart
@@ -3,6 +3,7 @@ import 'dart:async';
import 'package:flutter/foundation.dart';
import 'package:xterm/xterm.dart';
+import 'key_hints.dart';
import 'question_pane.dart';
/// Watches one terminal's buffer for an open question dialog.
@@ -22,9 +23,10 @@ import 'question_pane.dart';
/// a live question off the screen.
///
/// ⚠️ **Whoever listens must treat a repeat as nothing new.** This notifies on
-/// every CHANGE of dialog, including one question replacing another inside the
-/// same exchange; a listener that raises the keyboard on each notification
-/// would raise it again on a keyboard the person had deliberately put away.
+/// every CHANGE of dialog — and of Codex's queue of async questions ([queued])
+/// — including one question replacing another inside the same exchange; a
+/// listener that raises the keyboard on each notification would raise it again
+/// on a keyboard the person had deliberately put away.
class QuestionPaneWatcher extends ChangeNotifier {
QuestionPaneWatcher({required this.engine});
@@ -37,10 +39,29 @@ class QuestionPaneWatcher extends ChangeNotifier {
Timer? _debounce;
QuestionPaneView? _view;
int _misses = 0;
+ QueuedQuestions? _queued;
+ int _queuedMisses = 0;
+ List<KeyHint> _hints = const [];
+ int _hintMisses = 0;
/// The dialog currently on the pane, or null.
QuestionPaneView? get view => _view;
+ /// Codex's async questions waiting in its queue, or null — see
+ /// [parseQueuedQuestions]. Codex only.
+ ///
+ /// Debounced exactly as [view] is, and for the same reasons: it appears once
+ /// the buffer settles, and goes only after [_goneReads] reads without it.
+ QueuedQuestions? get queued => _queued;
+
+ /// The keys the pane's live chrome offers that a phone cannot press — see
+ /// [parseKeyHints]. Empty when there are none.
+ ///
+ /// Debounced as [view] is: a repaint caught mid-way reads as a bare pane,
+ /// and a row of buttons that blinked out on every redraw would be one
+ /// nobody could hit.
+ List<KeyHint> get hints => _hints;
+
/// How long the buffer must be quiet before it is read.
///
/// ⚠️ Long enough to outlast a repaint, short enough that the pad follows the
@@ -64,8 +85,10 @@ class QuestionPaneWatcher extends ChangeNotifier {
_debounce?.cancel();
_terminal = terminal;
_misses = 0;
+ _queuedMisses = 0;
+ _hintMisses = 0;
if (terminal == null) {
- _publish(null);
+ _publish(null, null, const []);
return;
}
if (engine == null) return;
@@ -85,7 +108,33 @@ class QuestionPaneWatcher extends ChangeNotifier {
final terminal = _terminal;
final engine = this.engine;
if (terminal == null || engine == null) return;
- final found = readQuestionPane(terminal, engine);
+ // One copy of the buffer for both readings.
+ final lines = questionPaneLines(terminal);
+ final dialog = _readDialog(
+ lines.isEmpty ? null : parseQuestionLines(lines, engine),
+ );
+ final queue = _readQueued(
+ engine == QuestionEngine.codex && lines.isNotEmpty
+ ? parseQueuedQuestions(lines)
+ : null,
+ );
+ final keys = _readHints(parseKeyHints(lines));
+ if (dialog.again || queue.again || keys.again) {
+ // ⚠️ **Ask for the next read rather than waiting for one.** Reads are
+ // driven by terminal output, and the engine may print NOTHING after the
+ // dialog closes — Codex repaints once on `esc` and then goes quiet. The
+ // first read saw the dialog gone, the second never came, and the pad
+ // stayed up over an answered question until the next keystroke.
+ // Measured on a Codex pane after `×`.
+ _debounce?.cancel();
+ _debounce = Timer(_settle, _read);
+ }
+ _publish(dialog.view, queue.queued, keys.hints);
+ }
+
+ /// What [found] makes of the open dialog: the view to keep, and whether to
+ /// read again without waiting for output.
+ ({QuestionPaneView? view, bool again}) _readDialog(QuestionPaneView? found) {
// Open but scrolled past its own top: still a dialog, so whatever is
// showing keeps showing. Not a miss, and not something to announce.
if (found != null && found.partial) {
@@ -93,41 +142,69 @@ class QuestionPaneWatcher extends ChangeNotifier {
// Keep looking, for the same reason the miss branch below does: a partial
// dialog that is then dismissed leaves a quiet pane, and a watcher that
// only wakes on output would never see it go.
- if (_view != null) {
- _debounce?.cancel();
- _debounce = Timer(_settle, _read);
- }
- return;
+ return (view: _view, again: _view != null);
}
if (found == null || !found.answerable) {
// Never had one: nothing to debounce, and counting misses forever would
// be pure noise.
- if (_view == null) return;
- if (++_misses < _goneReads) {
- // ⚠️ **Ask for the next read rather than waiting for one.** Reads are
- // driven by terminal output, and the engine may print NOTHING after the
- // dialog closes — Codex repaints once on `esc` and then goes quiet. The
- // first read saw the dialog gone, the second never came, and the pad
- // stayed up over an answered question until the next keystroke.
- // Measured on a Codex pane after `×`.
- _debounce?.cancel();
- _debounce = Timer(_settle, _read);
- return;
- }
+ if (_view == null) return (view: null, again: false);
+ if (++_misses < _goneReads) return (view: _view, again: true);
_misses = 0;
- _publish(null);
- return;
+ return (view: null, again: false);
}
_misses = 0;
// The same dialog redrawn — a caret moving between rows rewrites the whole
- // block. Publishing that would rebuild the pad on every arrow key.
- if (_view?.fingerprint == found.fingerprint) return;
- _publish(found);
+ // block. Keeping the one already held is what stops a publish on every
+ // arrow key.
+ if (_view?.fingerprint == found.fingerprint) {
+ return (view: _view, again: false);
+ }
+ return (view: found, again: false);
}
- void _publish(QuestionPaneView? next) {
- if (_view == null && next == null) return;
- _view = next;
+ /// The same, for Codex's queue of async questions.
+ ({QueuedQuestions? queued, bool again}) _readQueued(QueuedQuestions? found) {
+ if (found == null) {
+ if (_queued == null) return (queued: null, again: false);
+ // Gone only on the second read without it, as a dialog is: a repaint of
+ // Codex's bottom pane caught mid-way reads as no queue at all.
+ if (++_queuedMisses < _goneReads) return (queued: _queued, again: true);
+ _queuedMisses = 0;
+ return (queued: null, again: false);
+ }
+ _queuedMisses = 0;
+ return (queued: found, again: false);
+ }
+
+ /// The same, for the keys the chrome offers.
+ ({List<KeyHint> hints, bool again}) _readHints(List<KeyHint> found) {
+ if (found.isEmpty) {
+ if (_hints.isEmpty) return (hints: _hints, again: false);
+ if (++_hintMisses < _goneReads) return (hints: _hints, again: true);
+ _hintMisses = 0;
+ return (hints: const [], again: false);
+ }
+ _hintMisses = 0;
+ // The same keys redrawn: keep the list already held, so nothing is
+ // announced for a repaint.
+ if (listEquals(found, _hints)) return (hints: _hints, again: false);
+ return (hints: found, again: false);
+ }
+
+ /// Announce whatever changed — once, however much of it did.
+ void _publish(
+ QuestionPaneView? view,
+ QueuedQuestions? queued,
+ List<KeyHint> hints,
+ ) {
+ if (identical(view, _view) &&
+ queued == _queued &&
+ identical(hints, _hints)) {
+ return;
+ }
+ _view = view;
+ _queued = queued;
+ _hints = hints;
notifyListeners();
}