vtcode_commons/

diagnostics.rs

//! Sanitize the canonical payload before persistence, logging, and display.
pub use vtcode_exec_events::{Diagnostic, DiagnosticAction, DiagnosticSeverity};

use crate::ui_protocol::CommunicationStyle;

/// Apply the existing secret redaction to every externally supplied field.
/// Call before emitting a `ThreadEvent`, not merely when drawing its UI.
pub fn redact_diagnostic(diagnostic: &Diagnostic) -> Diagnostic {
    use crate::sanitizer::redact_secrets;
    let mut redacted = diagnostic.clone();
    redacted.code = redact_secrets(redacted.code);
    redacted.summary = redact_secrets(redacted.summary);
    redacted.agent_details = redact_secrets(redacted.agent_details);
    redacted.correlation_id = redact_secrets(redacted.correlation_id);
    for action in &mut redacted.actions {
        action.id = redact_secrets(std::mem::take(&mut action.id));
        action.label = redact_secrets(std::mem::take(&mut action.label));
    }
    redacted
}

/// Adapt legacy styled messages without dropping evidence after the summary.
/// Correlation identity belongs to the producer; this adapter does not authorize actions.
pub fn legacy_diagnostic(severity: DiagnosticSeverity, text: &str, correlation_id: String) -> Diagnostic {
    let text = crate::sanitizer::redact_secrets(text.to_owned());
    let mut lines = text.trim().splitn(2, '\n');
    let first = lines.next().unwrap_or_default();
    let (summary, details) = if first.len() <= 180 {
        (first.to_owned(), lines.next().unwrap_or_default().to_owned())
    } else {
        let summary = match severity {
            DiagnosticSeverity::Info => "Additional information is available. Expand Details for the full message.",
            DiagnosticSeverity::Warning => "A warning needs attention. Expand Details for the full message.",
            DiagnosticSeverity::Error => "An error needs attention. Expand Details for the full message.",
        };
        (summary.to_owned(), text.trim().to_owned())
    };
    let code = match severity {
        DiagnosticSeverity::Info => "runtime.info",
        DiagnosticSeverity::Warning => "runtime.warning",
        DiagnosticSeverity::Error => "runtime.error",
    };
    Diagnostic {
        severity,
        code: code.into(),
        summary,
        agent_details: details,
        correlation_id,
        actions: Vec::new(),
    }
}

/// Early-startup/headless diagnostic boundary before a thread event sink exists.
/// Formatting and redaction finish before stderr is touched.
pub fn stderr(arguments: std::fmt::Arguments<'_>) {
    let text = arguments.to_string();
    let lower = text.to_ascii_lowercase();
    let severity = if lower.contains("warn") || lower.contains("cancel") {
        DiagnosticSeverity::Warning
    } else {
        DiagnosticSeverity::Error
    };
    let diagnostic = legacy_diagnostic(severity, &text, "startup".into());
    stderr_diagnostic(&diagnostic);
}

/// Render a canonical diagnostic before any terminal UI is available.
pub fn stderr_diagnostic(diagnostic: &Diagnostic) {
    eprintln!("{}", redact_diagnostic(diagnostic).text());
}

/// Session-local observer shared by clones of one inline handle.
pub type DiagnosticSink = std::sync::Arc<dyn Fn(&Diagnostic) -> anyhow::Result<()> + Send + Sync>;

#[derive(Clone, Default)]
pub struct DiagnosticObserver(std::sync::Arc<std::sync::RwLock<DiagnosticObserverState>>);

#[derive(Default)]
struct DiagnosticObserverState {
    sink: Option<DiagnosticSink>,
    recent: std::collections::VecDeque<Diagnostic>,
}

impl std::fmt::Debug for DiagnosticObserver {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter.write_str("DiagnosticObserver")
    }
}

impl DiagnosticObserver {
    pub fn set_sink(&self, sink: DiagnosticSink) -> anyhow::Result<()> {
        let mut observer = self
            .0
            .write()
            .map_err(|error| anyhow::anyhow!("diagnostic observer lock poisoned: {error}"))?;
        observer.sink = Some(sink);
        observer.recent.clear();
        Ok(())
    }

    fn notify(&self, diagnostic: &Diagnostic) -> anyhow::Result<()> {
        let sink = {
            let observer = self
                .0
                .read()
                .map_err(|error| anyhow::anyhow!("diagnostic observer lock poisoned: {error}"))?;
            if observer.recent.iter().any(|previous| previous == diagnostic) {
                return Ok(());
            }
            observer.sink.clone()
        };
        let Some(sink) = sink else {
            return Ok(());
        };
        sink(diagnostic)?;
        let mut observer = self
            .0
            .write()
            .map_err(|error| anyhow::anyhow!("diagnostic observer lock poisoned: {error}"))?;
        observer
            .recent
            .retain(|previous| previous.correlation_id != diagnostic.correlation_id);
        if observer.recent.len() == 128 {
            let _ = observer.recent.pop_front();
        }
        observer.recent.push_back(diagnostic.clone());
        Ok(())
    }

    /// Void UI APIs report observer failures visibly and through sanitized telemetry.
    pub fn prepare(&self, diagnostic: &Diagnostic) -> Diagnostic {
        let mut diagnostic = redact_diagnostic(diagnostic);
        let result = self.notify(&diagnostic);
        if let Err(error) = result {
            let message = crate::sanitizer::sanitize_provider_diagnostic(error.to_string());
            tracing::warn!(error = %message, "canonical diagnostic persistence failed");
            if !diagnostic.agent_details.is_empty() {
                diagnostic.agent_details.push_str("\n\n");
            }
            diagnostic
                .agent_details
                .push_str("Diagnostic persistence failed; this message may not be saved.\n");
            diagnostic.agent_details.push_str(&message);
        }
        diagnostic
    }
}

/// Legacy calls represent separate incidents. Producers updating one incident
/// supply an explicit correlation identity through `Diagnostic` instead.
pub fn legacy_ui_diagnostic(severity: DiagnosticSeverity, text: &str) -> Diagnostic {
    legacy_diagnostic(severity, text, format!("legacy-{:032x}", rand::random::<u128>()))
}

/// Diagnostic codes that carry routine agent-internal failure evidence: the
/// agent loop consumes them, but they need no main-transcript row under the
/// default style. Everything else fails open to visible.
const ROUTINE_SILENT_CODES: &[&str] = &[
    // Agent-internal tool failure (preflight/validation/retry); the owning
    // tool row keeps its failed state and Review keeps the evidence.
    "tool.execution_failed",
    // Transient provider retry progress; the spinner already covers it.
    "provider.retrying",
    // A recovered retry is good news, not an incident.
    "provider.retry_succeeded",
];

/// Whether a diagnostic earns a main-transcript row under `style`.
///
/// Contract: persistence is never gated by this — callers persist the
/// canonical event first and consult this only at paint time. Unknown codes
/// fail open to visible; only the classified routine codes above (plus
/// `tool.command_failed` under `Quiet`) go silent.
/// `tool.policy_denied`, `tool.cancelled`, `provider.retry_stopped`, billing,
/// planning, MCP, and `runtime.*` incidents stay visible in every style.
#[must_use]
pub fn diagnostic_is_user_visible(style: CommunicationStyle, code: &str) -> bool {
    match style.resolve() {
        CommunicationStyle::Verbose => true,
        CommunicationStyle::Balanced => !ROUTINE_SILENT_CODES.contains(&code),
        CommunicationStyle::Quiet => code != "tool.command_failed" && !ROUTINE_SILENT_CODES.contains(&code),
        // `resolve` maps `Unknown` to `Balanced`; this arm is unreachable but
        // keeps the decision total if the mapping ever changes.
        CommunicationStyle::Unknown => !ROUTINE_SILENT_CODES.contains(&code),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn repeated_legacy_failures_are_distinct_incidents_but_explicit_incidents_deduplicate() {
        let observer = DiagnosticObserver::default();
        let captured = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
        let output = captured.clone();
        observer
            .set_sink(std::sync::Arc::new(move |diagnostic| {
                output.lock().unwrap().push(diagnostic.clone());
                Ok(())
            }))
            .unwrap();
        let mut ids = Vec::new();
        for _ in 0..2 {
            let diagnostic = legacy_ui_diagnostic(DiagnosticSeverity::Warning, "Clipboard unavailable");
            ids.push(observer.prepare(&diagnostic).correlation_id);
        }
        assert_ne!(ids[0], ids[1], "a repeated command failure is a new incident");
        let explicit = legacy_diagnostic(DiagnosticSeverity::Warning, "Retrying", "request-1".into());
        assert_eq!(observer.prepare(&explicit), explicit);
        assert_eq!(observer.prepare(&explicit), explicit);
        assert_eq!(captured.lock().unwrap().len(), 3);
    }
    #[test]
    fn diagnostic_redacts_summary_details_and_actions() {
        let diagnostic = Diagnostic {
            severity: DiagnosticSeverity::Error,
            code: "provider.failure".into(),
            summary: "Authorization: Bearer secret-summary-value".into(),
            agent_details: "password=secret-detail-value".into(),
            correlation_id: "request-2".into(),
            actions: vec![DiagnosticAction {
                id: "retry".into(),
                label: "api_key=secret-action-value".into(),
            }],
        };
        let text = serde_json::to_string(&redact_diagnostic(&diagnostic)).unwrap();
        for secret in ["secret-summary-value", "secret-detail-value", "secret-action-value"] {
            assert!(!text.contains(secret), "leaked {secret}");
        }
        assert!(text.contains("provider.failure"));
        assert!(text.contains("request-2"));
    }
    #[test]
    fn communication_style_visibility_silences_only_routine_codes() {
        use crate::ui_protocol::CommunicationStyle;
        // Asymmetric matrix: every style sees both a silent and a visible code
        // except Verbose, which is the deliberate show-everything escape hatch.
        for (style, code, visible) in [
            (CommunicationStyle::Balanced, "tool.execution_failed", false),
            (CommunicationStyle::Balanced, "provider.retrying", false),
            (CommunicationStyle::Balanced, "provider.retry_succeeded", false),
            (CommunicationStyle::Balanced, "tool.command_failed", true),
            (CommunicationStyle::Balanced, "tool.policy_denied", true),
            (CommunicationStyle::Balanced, "tool.cancelled", true),
            (CommunicationStyle::Balanced, "provider.retry_stopped", true),
            (CommunicationStyle::Balanced, "provider.stream_billing_advisory", true),
            (CommunicationStyle::Balanced, "planning.awaiting_input", true),
            (CommunicationStyle::Balanced, "mcp.catalog_failed", true),
            (CommunicationStyle::Balanced, "runtime.error", true),
            (CommunicationStyle::Quiet, "tool.execution_failed", false),
            (CommunicationStyle::Quiet, "tool.command_failed", false),
            (CommunicationStyle::Quiet, "tool.policy_denied", true),
            (CommunicationStyle::Quiet, "provider.retry_stopped", true),
            (CommunicationStyle::Verbose, "tool.execution_failed", true),
            (CommunicationStyle::Verbose, "provider.retrying", true),
            (CommunicationStyle::Verbose, "tool.command_failed", true),
            // Fail-open: an unknown future code is visible everywhere.
            (CommunicationStyle::Balanced, "tool.something_new", true),
            (CommunicationStyle::Quiet, "tool.something_new", true),
            // An unknown future style degrades to Balanced, never to silence.
            (CommunicationStyle::Unknown, "tool.execution_failed", false),
            (CommunicationStyle::Unknown, "tool.command_failed", true),
        ] {
            assert_eq!(
                diagnostic_is_user_visible(style, code),
                visible,
                "{style:?} must treat {code} as visible={visible}"
            );
        }
    }

    #[test]
    fn communication_style_parse_round_trips_and_falls_back_to_unknown() {
        use crate::ui_protocol::CommunicationStyle;
        for (text, expected) in [
            ("balanced", CommunicationStyle::Balanced),
            ("  Quiet ", CommunicationStyle::Quiet),
            ("VERBOSE", CommunicationStyle::Verbose),
            ("", CommunicationStyle::Unknown),
            ("terse", CommunicationStyle::Unknown),
        ] {
            assert_eq!(CommunicationStyle::parse(text), expected, "parse({text:?})");
        }
        assert_eq!(CommunicationStyle::Unknown.resolve(), CommunicationStyle::Balanced);
        assert_eq!(CommunicationStyle::default(), CommunicationStyle::Balanced);
        assert_eq!(
            serde_json::from_value::<CommunicationStyle>(serde_json::json!("verbose")).unwrap(),
            CommunicationStyle::Verbose
        );
        assert_eq!(
            serde_json::from_value::<CommunicationStyle>(serde_json::json!("future-style")).unwrap(),
            CommunicationStyle::Unknown
        );
    }

    #[test]
    fn diagnostic_long_message_preserves_complete_command_and_short_message_body() {
        let command =
            format!("Run `/a/very/long/path/{} --exact` to recover.\nExpected: exit zero.", "segment/".repeat(40));
        let diagnostic = legacy_diagnostic(DiagnosticSeverity::Error, &command, "incident-7".into());
        assert_eq!(diagnostic.summary, "An error needs attention. Expand Details for the full message.");
        assert_eq!(diagnostic.agent_details, command);
        let short =
            legacy_diagnostic(DiagnosticSeverity::Warning, "Retry needs input.\nAttempts: 3", "incident-8".into());
        assert_eq!(short.summary, "Retry needs input.");
        assert_eq!(short.agent_details, "Attempts: 3");
    }
}