supercode-cli 0.5.84

//! UX-21: OSC terminal-title updates — sets the terminal window/tab title to
//! reflect Volter Harness's current activity (`Volter Harness · <model>` while idle at
//! the prompt, `Volter Harness · <model> · thinking…` while a turn is in flight)
//! so a session is identifiable among other tabs, and restores whatever
//! title was there before on exit.
//!
//! Design goals (mirroring `spinner.rs`'s and `ui.rs`'s established shape —
//! see `spinner::should_show_spinner` / `ui::detect_color_level`):
//! - Zero-dependency: two escape-sequence writes, no crate.
//! - Byte-clean on any non-interactive path: piped/redirected stderr,
//!   `--quiet`/`SUPERCODE_QUIET`, or a dumb terminal must never see a single
//!   title byte. Achieved by never emitting anything when
//!   [`should_set_title`] says no — the single choke point, same discipline
//!   as `Spinner::enabled`.
//! - Never touches stdout: the OSC bytes go to stderr only, so `run
//!   --output-format json` / piped answers are never at risk of an escape
//!   sequence landing in machine-readable output.
//! - Restores on exit: [`TitleGuard::enter`] pushes the terminal's current
//!   title onto its title stack (xterm window-ops `CSI 22 ; 0 t`) before
//!   setting the first title; `Drop` pops it back (`CSI 23 ; 0 t`) on every
//!   exit path (normal return, `?`, or panic-unwind) — the same
//!   belt-and-suspenders teardown `Spinner`'s `Drop` uses.

use std::io::{IsTerminal, Write};

/// Push the current title onto the terminal's title stack (xterm window
/// manipulation, `CSI 22 ; 0 t` with the `0` parameter meaning "both icon
/// and window title"). Widely supported (xterm, most VTE-based terminals,
/// iTerm2, Windows Terminal); on a terminal that doesn't understand it, it's
/// silently ignored like any unrecognized CSI sequence.
const PUSH_TITLE: &str = "\x1b[22;0t";
/// Pop the previously-pushed title back off the stack, restoring whatever
/// the terminal showed before supercode started touching it.
const POP_TITLE: &str = "\x1b[23;0t";

/// The activity supercode's title should reflect. Deliberately just two
/// states (idle / thinking) — the AC calls for "model / running / idle",
/// and "running" and "thinking" are the same state from the title's
/// perspective (a turn is in flight).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum TitleState {
    /// At the REPL prompt, waiting for input.
    Idle,
    /// A turn (`agent.send`) is in flight.
    Thinking,
}

/// Pure decision function for "should the title ever be touched?" — no I/O,
/// unit-testable without a real tty or mutated env vars, the same shape as
/// `spinner::should_show_spinner`.
///
/// Title emission is suppressed when:
/// - the caller is in `--quiet`/`SUPERCODE_QUIET` mode (`quiet`) — UX-21
///   dev/02;
/// - `TERM=dumb` (a terminal that declares no capabilities shouldn't be
///   sent window-manipulation escapes); or
/// - stderr isn't a terminal (piped/redirected/non-interactive — UX-21
///   dev/02's "non-tty/piped" case; this is also what makes `run
///   --output-format json` and any non-interactive path byte-clean, since
///   those never construct a `TitleGuard` enabled in the first place).
pub(crate) fn should_set_title(quiet: bool, term_dumb: bool, stderr_is_tty: bool) -> bool {
    !(quiet || term_dumb || !stderr_is_tty)
}

/// Real-world gating: reads `TERM` and stderr's tty-ness. `quiet` is
/// threaded in by the caller, exactly like `spinner::should_show_spinner_now`
/// — every call site passes `main.rs`'s `effective_quiet(cli)`
/// (`cli.quiet || SUPERCODE_QUIET`), so the flag and the env var can never
/// give different answers.
fn should_set_title_now(quiet: bool) -> bool {
    should_set_title(
        quiet,
        std::env::var("TERM").ok().as_deref() == Some("dumb"),
        std::io::stderr().is_terminal(),
    )
}

/// Strip control characters (including ESC/BEL) from a title component
/// before it's interpolated into an OSC sequence. `model` ultimately comes
/// from `--model`/config — untrusted enough that a crafted value containing
/// an embedded `ESC`/`BEL` must not be able to break out of the title
/// sequence and inject arbitrary escapes into the user's terminal.
fn sanitize(s: &str) -> String {
    s.chars().filter(|c| !c.is_control()).collect()
}

/// Build the title string for a given model/state, e.g.
/// `"Volter Harness · claude-opus-4-6 · thinking…"`.
fn title_for(model: &str, state: TitleState) -> String {
    let model = sanitize(model);
    match state {
        TitleState::Idle => format!("Volter Harness · {model}"),
        TitleState::Thinking => format!("Volter Harness · {model} · thinking…"),
    }
}

/// Emit an OSC 0 (icon + window title) set sequence: `ESC ] 0 ; <title> BEL`.
/// Written to stderr only, never stdout, and flushed immediately so it lands
/// before whatever the caller prints next.
fn emit_set(title: &str) {
    let mut out = std::io::stderr();
    let _ = write!(out, "\x1b]0;{title}\x07");
    let _ = out.flush();
}

/// RAII scope for a title-managed interactive session (the REPL, `chat()`).
/// Construct once via [`TitleGuard::enter`] at the top of the session;
/// [`TitleGuard::set`] updates it on turn start/finish; `Drop` restores the
/// terminal's previous title on every exit path. A disabled guard (gating
/// says no) is a true no-op end to end — `enter`/`set`/`drop` never touch
/// stderr — so `--quiet`/non-tty/dumb-terminal sessions stay byte-clean.
pub(crate) struct TitleGuard {
    enabled: bool,
}

impl TitleGuard {
    /// Enter a title-managed scope for `model`: if gating allows, push the
    /// terminal's current title and set the initial `Idle` title. `quiet`
    /// should be the caller's already-computed `effective_quiet(cli)`.
    pub(crate) fn enter(quiet: bool, model: &str) -> Self {
        let enabled = should_set_title_now(quiet);
        if enabled {
            let mut out = std::io::stderr();
            let _ = write!(out, "{PUSH_TITLE}");
            let _ = out.flush();
        }
        let guard = Self { enabled };
        guard.set(model, TitleState::Idle);
        guard
    }

    /// Update the title to reflect `model`/`state`. No-op when disabled.
    pub(crate) fn set(&self, model: &str, state: TitleState) {
        if !self.enabled {
            return;
        }
        emit_set(&title_for(model, state));
    }
}

impl Drop for TitleGuard {
    fn drop(&mut self) {
        // Belt-and-suspenders teardown on every exit path (early return,
        // `?`, panic-unwind), mirroring `Spinner`'s `Drop` — pop restores
        // whatever title the terminal showed before `enter()`.
        if self.enabled {
            let mut out = std::io::stderr();
            let _ = write!(out, "{POP_TITLE}");
            let _ = out.flush();
        }
    }
}