1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
//! The one port through which runtime code causes terminal side effects.
//!
//! The terminal UI is the only owner of the terminal: it alone toggles raw
//! mode and writes escape sequences. Runtime code (tools, the engine, the
//! runtime API) never links a terminal library; when it needs a terminal
//! effect it asks the installed [`HostTerminal`]. The composition root
//! installs the TUI's implementation once at startup, for every host it
//! launches today (interactive TUI, `exec`, the runtime API server), so
//! behavior is unchanged from when the calls were inline.
//!
//! With nothing installed every method is a no-op. That is the intended
//! future shape for stdio hosts (ACP, MCP server, app-server), whose stdout is
//! a JSON-RPC stream that must never receive terminal bytes.
//!
//! Known limitations: the install is process-global and first-wins; a
//! process cannot swap hosts after startup, and tests that need the real
//! terminal behavior must go through the TUI's own implementation.
use std::sync::OnceLock;
use codewhale_config::notifications::NotificationsConfig;
/// Terminal side effects the runtime may request from its host.
pub trait HostTerminal: Send + Sync {
/// Leave raw mode if it is on, so an interactive child process sees a
/// cooked terminal. Returns whether raw mode was on (and must be resumed).
fn suspend_raw_mode(&self) -> bool;
/// Re-enter raw mode after [`HostTerminal::suspend_raw_mode`] returned
/// `true`.
fn resume_raw_mode(&self);
/// Deliver a model-authored notification (the `notify` tool) now,
/// honoring the installed notification settings. Returns the delivery
/// receipt the tool reports to the model.
fn notify_model(&self, title: &str, body: Option<&str>) -> &'static str;
/// Record whether the terminal has focus; attention policy reads it.
fn set_terminal_focused(&self, focused: bool);
/// Install the process-wide notification method, category gate, sound
/// policy and attention condition from `[notifications]`.
fn apply_notification_settings(&self, config: &NotificationsConfig);
fn begin_turn_chrome(&self) {}
}
struct NoHostTerminal;
impl HostTerminal for NoHostTerminal {
fn suspend_raw_mode(&self) -> bool {
false
}
fn resume_raw_mode(&self) {}
fn notify_model(&self, _title: &str, _body: Option<&str>) -> &'static str {
"notification not sent: no terminal host"
}
fn set_terminal_focused(&self, _focused: bool) {}
fn apply_notification_settings(&self, _config: &NotificationsConfig) {}
}
static HOST: OnceLock<Box<dyn HostTerminal>> = OnceLock::new();
/// Install the process's terminal host. The first install wins; later calls
/// are ignored and return `false`.
pub fn install(host: Box<dyn HostTerminal>) -> bool {
HOST.set(host).is_ok()
}
/// The installed terminal host, or a no-op host when none is installed.
#[must_use]
pub fn host() -> &'static dyn HostTerminal {
match HOST.get() {
Some(host) => host.as_ref(),
None => &NoHostTerminal,
}
}
/// Raw mode suspended for the lifetime of this guard (issue #1690).
///
/// Created by [`suspend_raw_mode`]; dropping it resumes raw mode only if it
/// was on when the guard was created.
#[must_use = "raw mode is resumed when the guard drops"]
pub struct RawModeSuspension {
/// The host that suspended raw mode resumes it.
host: &'static dyn HostTerminal,
resume: bool,
}
/// Leave raw mode around an interactive child; resume it when the returned
/// guard drops, only if it was on to begin with.
pub fn suspend_raw_mode() -> RawModeSuspension {
suspend_raw_mode_on(host())
}
fn suspend_raw_mode_on(host: &'static dyn HostTerminal) -> RawModeSuspension {
RawModeSuspension {
host,
resume: host.suspend_raw_mode(),
}
}
impl Drop for RawModeSuspension {
fn drop(&mut self) {
if self.resume {
self.host.resume_raw_mode();
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
/// Records raw-mode calls. Each test owns its own `static` instance, so
/// they never share counters.
struct CountingHost {
raw: AtomicBool,
suspends: AtomicUsize,
resumes: AtomicUsize,
}
impl CountingHost {
const fn new(raw: bool) -> Self {
Self {
raw: AtomicBool::new(raw),
suspends: AtomicUsize::new(0),
resumes: AtomicUsize::new(0),
}
}
}
impl HostTerminal for CountingHost {
fn suspend_raw_mode(&self) -> bool {
self.suspends.fetch_add(1, Ordering::SeqCst);
self.raw.swap(false, Ordering::SeqCst)
}
fn resume_raw_mode(&self) {
self.resumes.fetch_add(1, Ordering::SeqCst);
self.raw.store(true, Ordering::SeqCst);
}
fn notify_model(&self, _title: &str, _body: Option<&str>) -> &'static str {
"unused"
}
fn set_terminal_focused(&self, _focused: bool) {}
fn apply_notification_settings(&self, _config: &NotificationsConfig) {}
}
#[test]
fn no_host_suspension_is_a_no_op() {
// No host is installed in this test binary: suspending reports raw
// mode off, so the guard never asks to resume it.
let guard = suspend_raw_mode();
assert!(!guard.resume);
}
#[test]
fn raw_mode_that_was_on_is_resumed_exactly_once_when_the_guard_drops() {
static HOST: CountingHost = CountingHost::new(true);
let guard = suspend_raw_mode_on(&HOST);
assert!(
!HOST.raw.load(Ordering::SeqCst),
"raw mode is off while suspended"
);
assert_eq!(HOST.resumes.load(Ordering::SeqCst), 0);
drop(guard);
assert!(
HOST.raw.load(Ordering::SeqCst),
"raw mode is back on after the guard"
);
assert_eq!(HOST.suspends.load(Ordering::SeqCst), 1);
assert_eq!(HOST.resumes.load(Ordering::SeqCst), 1);
}
#[test]
fn raw_mode_that_was_off_is_never_turned_on_by_the_guard() {
static HOST: CountingHost = CountingHost::new(false);
drop(suspend_raw_mode_on(&HOST));
assert_eq!(HOST.suspends.load(Ordering::SeqCst), 1);
assert_eq!(HOST.resumes.load(Ordering::SeqCst), 0);
assert!(!HOST.raw.load(Ordering::SeqCst));
}
}