feat: implement in-flight error handling

Author: gitcoder89431

Cargo.lock

@@ -12,3 +12,4 @@ reqwest = { workspace = true }
 tokio = { workspace = true }
 anyhow = { workspace = true }
 serde_json = { workspace = true }
+thiserror.workspace = true

crates/agentic-core/Cargo.toml

@@ -1,18 +1,64 @@
+use crate::models::AtomicNote;
 use reqwest::Client;
 use serde::{Deserialize, Serialize};
 use std::time::Duration;
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum CloudError {
+    #[error("The cloud provider rejected the API key. It might have expired or been disabled.")]
+    ApiKey,
+
+    #[error("The cloud model returned a response that could not be understood.")]
+    ParseError,
+
+    #[error("The cloud provider returned an unexpected error: {status}: {text}")]
+    ApiError {
+        status: u16,
+        text: String,
+    },
+
+    #[error(transparent)]
+    RequestError(#[from] reqwest::Error),
+}
+
+const SYNTHESIZER_PROMPT: &str = r#"You are an expert-level AI Synthesizer. Your task is to answer the user's prompt by generating a concise, "atomic note" of knowledge.
+
+CRITICAL OUTPUT CONSTRAINTS:
+
+Header (Metadata): You MUST generate a set of 3-5 semantic keywords or tags that capture the absolute essence of the topic. These tags are for a knowledge graph.
+
+Body (Content): The main response MUST be a maximum of four (4) sentences. It must be a dense, self-contained summary of the most critical information.
+
+OUTPUT FORMAT (JSON):
+Your final output MUST be a single, valid JSON object with two keys: header_tags and body_text.
+
+{
+  "header_tags": ["keyword1", "keyword2", "keyword3"],
+  "body_text": "Your concise, 3-4 sentence summary goes here."
+}
+
+USER PROMPT:
+{prompt}
+"#;
+
+#[derive(Serialize)]
+struct ResponseFormat {
+    r#type: String,
+}
 
 #[derive(Serialize)]
-struct OpenRouterRequest {
+struct OpenRouterRequest<'a> {
     model: String,
-    messages: Vec<ChatMessage>,
+    messages: Vec<ChatMessage<'a>>,
     max_tokens: u32,
+    response_format: ResponseFormat,
 }
 
 #[derive(Serialize)]
-struct ChatMessage {
+struct ChatMessage<'a> {
     role: String,
-    content: String,
+    content: &'a str,
 }
 
 #[derive(Deserialize)]
@@ -34,22 +80,21 @@ pub async fn call_cloud_model(
     api_key: &str,
     model: &str,
     prompt: &str,
-) -> Result<String, anyhow::Error> {
+) -> Result<AtomicNote, CloudError> {
     let client = Client::builder().timeout(Duration::from_secs(30)).build()?;
 
-    // Optimize prompt for concise responses
-    let optimized_prompt = format!(
-        "Please provide a concise, well-structured response to this inquiry. Keep it informative but focused:\n\n{}",
-        prompt
-    );
+    let synthesizer_prompt = SYNTHESIZER_PROMPT.replace("{prompt}", prompt);
 
     let request_body = OpenRouterRequest {
         model: model.to_string(),
         messages: vec![ChatMessage {
             role: "user".to_string(),
-            content: optimized_prompt,
+            content: &synthesizer_prompt,
         }],
-        max_tokens: 1024, // Reduced from 2048 for more concise responses
+        max_tokens: 1024,
+        response_format: ResponseFormat {
+            r#type: "json_object".to_string(),
+        },
     };
 
     let response = client
@@ -62,19 +107,29 @@ pub async fn call_cloud_model(
 
     if !response.status().is_success() {
         let status = response.status();
+        if status == 401 {
+            return Err(CloudError::ApiKey);
+        }
         let error_text = response.text().await.unwrap_or_default();
-        return Err(anyhow::anyhow!(
-            "OpenRouter API error {}: {}",
-            status,
-            error_text
-        ));
+        return Err(CloudError::ApiError {
+            status: status.as_u16(),
+            text: error_text,
+        });
     }
 
-    let openrouter_response: OpenRouterResponse = response.json().await?;
+    let openrouter_response: OpenRouterResponse = match response.json().await {
+        Ok(res) => res,
+        Err(_) => return Err(CloudError::ParseError),
+    };
 
-    if let Some(choice) = openrouter_response.choices.first() {
-        Ok(choice.message.content.clone())
-    } else {
-        Err(anyhow::anyhow!("No response choices from OpenRouter API"))
-    }
-}
+    let message_content = openrouter_response
+        .choices
+        .first()
+        .map(|choice| &choice.message.content)
+        .ok_or(CloudError::ParseError)?;
+
+    let atomic_note: AtomicNote =
+        serde_json::from_str(message_content).map_err(|_| CloudError::ParseError)?;
+
+    Ok(atomic_note)
+}

crates/agentic-core/src/cloud.rs

@@ -4,6 +4,12 @@ use serde::{Deserialize, Serialize};
 use serde_json::Value;
 use std::time::Duration;
 
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AtomicNote {
+    pub header_tags: Vec<String>,
+    pub body_text: String,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct OllamaModel {
     pub name: String,

crates/agentic-core/src/models.rs

@@ -6,8 +6,8 @@ use super::{
     settings_modal::render_settings_modal,
 };
 use agentic_core::{
-    cloud,
-    models::{ModelValidator, OllamaModel, OpenRouterModel},
+    cloud::{self, CloudError},
+    models::{AtomicNote, ModelValidator, OllamaModel, OpenRouterModel},
     orchestrator,
     settings::{Settings, ValidationError},
     theme::{Element, Theme},
@@ -66,7 +66,7 @@ pub enum ValidationMessage {
 pub enum AgentMessage {
     ProposalsGenerated(Result<Vec<String>, anyhow::Error>),
     RevisedProposalGenerated(Result<String, anyhow::Error>),
-    CloudSynthesisComplete(Result<String, anyhow::Error>),
+    CloudSynthesisComplete(Result<AtomicNote, CloudError>),
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
@@ -123,8 +123,9 @@ pub struct App {
     proposals: Vec<String>,
     current_proposal_index: usize,
     final_prompt: String,
-    cloud_response: String,
+    cloud_response: Option<AtomicNote>,
     synthesis_scroll: u16,
+    coaching_tip: (String, String),
 }
 
 impl App {
@@ -150,8 +151,9 @@ impl App {
             proposals: Vec::new(),
             current_proposal_index: 0,
             final_prompt: String::new(),
-            cloud_response: String::new(),
+            cloud_response: None,
             synthesis_scroll: 0,
+            coaching_tip: (String::new(), String::new()),
         }
     }
 
@@ -248,10 +250,12 @@ impl App {
     }
 
     fn render_coaching_tip_modal(&self, frame: &mut ratatui::Frame, area: Rect) {
-        use ratatui::{prelude::Alignment, text::Line, widgets::Paragraph};
+        use ratatui::{prelude::Alignment, widgets::Paragraph};
+
+        let (title, message) = &self.coaching_tip;
 
         let block = Block::default()
-            .title(" Coaching Tip ")
+            .title(format!(" {} ", title))
             .borders(Borders::ALL)
             .style(self.theme.ratatui_style(Element::Active));
 
@@ -267,19 +271,7 @@ impl App {
             ])
             .split(inner_area);
 
-        // Main coaching message with tips
-        let message_text = vec![
-            Line::from(""),
-            Line::from("Ruixen is having a tough time with this abstract query."),
-            Line::from(""),
-            Line::from(":: Smaller local models work best with clear and concrete questions."),
-            Line::from(""),
-            Line::from(":: Try a more direct question, add specific context, or break"),
-            Line::from("   the query down into smaller steps."),
-            Line::from(""),
-        ];
-
-        let message = Paragraph::new(message_text)
+        let message = Paragraph::new(message.as_str())
             .alignment(Alignment::Center)
             .style(self.theme.ratatui_style(Element::Text))
             .wrap(Wrap { trim: true });
@@ -467,13 +459,33 @@ impl App {
                 frame.render_widget(Clear, modal_area);
                 self.render_coaching_tip_modal(frame, modal_area);
             } else if self.mode == AppMode::Complete {
+                let content = if let Some(note) = &self.cloud_response {
+                    use ratatui::text::{Line, Span};
+                    let title = note.header_tags.join(" • ");
+                    let title_style = self.theme.ratatui_style(Element::Accent);
+                    let body_style = self.theme.ratatui_style(Element::Text);
+
+                    let text = vec![
+                        Line::from(Span::styled(title, title_style)),
+                        Line::from(""), // Spacer
+                        Line::from(Span::styled(&note.body_text, body_style)),
+                    ];
+                    Paragraph::new(text)
+                } else {
+                    // This case should ideally not be reached if mode is Complete
+                    Paragraph::new("Waiting for synthesis...")
+                };
+
                 let block = Block::default()
-                    .title("Synthesis Complete")
-                    .borders(Borders::ALL);
-                let paragraph = Paragraph::new(self.cloud_response.as_str())
+                    .title(" Synthesis Complete ")
+                    .borders(Borders::ALL)
+                    .style(self.theme.ratatui_style(Element::Active));
+
+                let paragraph = content
                     .block(block)
                     .wrap(Wrap { trim: true })
                     .scroll((self.synthesis_scroll, 0));
+
                 frame.render_widget(paragraph, app_chunks[1]);
             } else {
                 render_chat(
@@ -594,7 +606,10 @@ impl App {
                 self.agent_status = AgentStatus::Ready;
             }
             AgentMessage::ProposalsGenerated(Err(_e)) => {
-                // Show coaching tip instead of just failing silently
+                self.coaching_tip = (
+                    "Local Model Error".to_string(),
+                    "The local model failed to generate proposals. Check if it is running and configured correctly.".to_string(),
+                );
                 self.mode = AppMode::CoachingTip;
                 self.agent_status = AgentStatus::Ready;
             }
@@ -604,16 +619,34 @@ impl App {
                 self.agent_status = AgentStatus::Ready;
             }
             AgentMessage::RevisedProposalGenerated(Err(_e)) => {
-                // TODO: Set error state and display to user
+                self.coaching_tip = (
+                    "Local Model Error".to_string(),
+                    "The local model failed to revise the proposal. Check if it is running and configured correctly.".to_string(),
+                );
+                self.mode = AppMode::CoachingTip;
                 self.agent_status = AgentStatus::Ready;
             }
             AgentMessage::CloudSynthesisComplete(Ok(response)) => {
-                self.cloud_response = response;
+                self.cloud_response = Some(response);
                 self.mode = AppMode::Complete;
                 self.agent_status = AgentStatus::Complete;
             }
-            AgentMessage::CloudSynthesisComplete(Err(_e)) => {
-                // Show coaching tip for cloud API failures
+            AgentMessage::CloudSynthesisComplete(Err(e)) => {
+                let (title, message) = match e {
+                    CloudError::ApiKey => (
+                        "API Key Error".to_string(),
+                        "The cloud provider rejected the API key. It might have expired or been disabled. Please verify your key in the settings menu.".to_string(),
+                    ),
+                    CloudError::ParseError => (
+                        "Cloud Model Error".to_string(),
+                        "Ruixen was unable to parse the response from the cloud model. This can sometimes happen with very complex or ambiguous queries. Try rephrasing your prompt, or attempt the synthesis again.".to_string(),
+                    ),
+                    _ => (
+                        "Cloud API Error".to_string(),
+                        format!("An unexpected error occurred with the cloud provider: {}.", e),
+                    ),
+                };
+                self.coaching_tip = (title, message);
                 self.mode = AppMode::CoachingTip;
                 self.agent_status = AgentStatus::Ready;
             }
@@ -907,7 +940,7 @@ impl App {
                                 self.final_prompt.clear();
                                 self.proposals.clear();
                                 self.current_proposal_index = 0;
-                                self.cloud_response.clear();
+                                self.cloud_response = None;
                                 self.synthesis_scroll = 0;
                                 self.agent_status = AgentStatus::Ready;
                             }