feat(ux): 4-phase extreme UX improvement

Phase 1 — Smart tool tiering:
- Add ToolTier (Core/Standard/Extended) and ToolCategory enums
- Annotate all 40+ tools with tier and category classifications
- Add tier()/categories() default methods to Tool trait

Phase 2 — Zero-config startup (prx go):
- New `prx go` subcommand for instant start with -k flag
- File-based credential detection (auth-profiles, config.toml, Claude OAuth)
- Provider/model auto-inference from API key prefix

Phase 3 — Structured error experience:
- Did-you-mean suggestions for unknown tool names (strsim)
- Schema-aware missing parameter formatting
- Context-sensitive recovery hints for common errors
- Repeated failure detection with guidance injection

Phase 4 — Perception enhancement:
- Dynamic braille spinner during LLM thinking
- Tool execution duration display (e.g. "shell (1.2s)")
- Multi-step progress indicators for tool iterations

Author: g1e2x87

Cargo.lock

@@ -4,7 +4,7 @@ resolver = "2"
 
 [package]
 name = "openprx"
-version = "0.3.0"
+version = "0.3.1"
 edition = "2024"
 authors = ["g1e2x87"]
 license = "MIT OR Apache-2.0"
@@ -69,6 +69,9 @@ fantoccini = { version = "0.22.0", optional = true, default-features = false, fe
 anyhow = "1.0"
 thiserror = "2.0"
 
+# String similarity for tool name suggestions
+strsim = "0.11"
+
 # UUID generation
 uuid = { version = "1.11", default-features = false, features = ["v4", "v7", "std"] }
 
@@ -177,6 +180,9 @@ probe-rs = { version = "0.31", optional = true }
 pdf-extract = { version = "0.10", optional = true }
 tokio-stream = { version = "0.1.18", features = ["full"] }
 
+# Temporary directory for zero-config `prx go` workspace
+tempfile = "3.14"
+
 # WhatsApp Web client (wa-rs) — optional, enable with --features whatsapp-web
 # Uses wa-rs for Bot and Client, wa-rs-core for storage traits, custom rusqlite backend avoids Diesel conflict.
 wa-rs = { version = "0.2", optional = true, default-features = false }
@@ -247,7 +253,6 @@ strip = true
 panic = "abort"
 
 [dev-dependencies]
-tempfile = "3.14"
 
 [workspace.lints.rust]
 unsafe_code = "deny"

Cargo.toml

@@ -519,12 +519,24 @@ impl Agent {
                     let output = if r.success {
                         r.output
                     } else {
-                        format!("Error: {}", r.error.unwrap_or(r.output))
+                        let error_text = r.error.unwrap_or(r.output);
+                        let hint = crate::tools::error_hints::recovery_hint(&call.name, &error_text);
+                        if hint.is_empty() {
+                            format!("Error: {error_text}")
+                        } else {
+                            format!("Error: {error_text}\n{hint}")
+                        }
                     };
                     (output, actual_success)
                 }
                 Err(e) => {
-                    let message = format!("Error executing {}: {e}", call.name);
+                    let error_str = e.to_string();
+                    let hint = crate::tools::error_hints::recovery_hint(&call.name, &error_str);
+                    let message = if hint.is_empty() {
+                        format!("Error executing {}: {error_str}", call.name)
+                    } else {
+                        format!("Error executing {}: {error_str}\n{hint}", call.name)
+                    };
                     self.hooks.emit(HookEvent::Error, payload_error("tool", &message)).await;
                     self.observer.record_event(&ObserverEvent::ToolCall {
                         tool: call.name.clone(),
@@ -535,7 +547,14 @@ impl Agent {
                 }
             }
         } else {
-            let message = format!("Unknown tool: {}", call.name);
+            let available_names: Vec<&str> = self.tools.iter().map(|t| t.name()).collect();
+            let suggestion = crate::tools::error_hints::suggest_tool_name(&call.name, &available_names);
+            let hint = suggestion.map(|s| format!(" Did you mean '{s}'?")).unwrap_or_default();
+            let message = format!(
+                "Error: unknown tool '{}'.{hint}\nAvailable tools: {}",
+                call.name,
+                available_names.join(", ")
+            );
             self.hooks.emit(HookEvent::Error, payload_error("tool", &message)).await;
             (message, false)
         };

src/agent/agent.rs

@@ -31,7 +31,13 @@ pub(crate) enum ToolCallNotification {
     /// A tool call is about to be executed.
     Started { name: String, args_summary: String },
     /// A tool call has finished executing.
-    Finished { name: String, success: bool },
+    Finished {
+        name: String,
+        success: bool,
+        duration_ms: u64,
+    },
+    /// Progress indication for multi-iteration tool loops.
+    Progress { iteration: usize, max_iterations: usize },
 }
 
 /// Context for scope-based tool access control.
@@ -1599,7 +1605,13 @@ async fn execute_one_tool(
     scope_ctx: Option<&ScopeContext<'_>>,
 ) -> Result<String> {
     let Some(tool) = find_tool(tools_registry, call_name) else {
-        return Ok(format!("Unknown tool: {call_name}"));
+        let available_names: Vec<&str> = tools_registry.iter().map(|t| t.name()).collect();
+        let suggestion = crate::tools::error_hints::suggest_tool_name(call_name, &available_names);
+        let hint = suggestion.map(|s| format!(" Did you mean '{s}'?")).unwrap_or_default();
+        return Ok(format!(
+            "Error: unknown tool '{call_name}'.{hint}\nAvailable tools: {}",
+            available_names.join(", ")
+        ));
     };
 
     let root = call_arguments
@@ -1639,9 +1651,8 @@ async fn execute_one_tool(
                 .filter(|key| !args_obj.contains_key(*key))
                 .collect();
             if !missing.is_empty() {
-                return Ok(format!(
-                    "Error: missing required argument(s) for tool '{call_name}': {}",
-                    missing.join(", ")
+                return Ok(crate::tools::error_hints::format_missing_params(
+                    call_name, &missing, &schema,
                 ));
             }
         }
@@ -1672,7 +1683,13 @@ async fn execute_one_tool(
             if r.success {
                 Ok(scrub_credentials(&r.output))
             } else {
-                Ok(format!("Error: {}", r.error.unwrap_or_else(|| r.output)))
+                let error_text = r.error.unwrap_or_else(|| r.output);
+                let hint = crate::tools::error_hints::recovery_hint(call_name, &error_text);
+                if hint.is_empty() {
+                    Ok(format!("Error: {error_text}"))
+                } else {
+                    Ok(format!("Error: {error_text}\n{hint}"))
+                }
             }
         }
         Err(e) => {
@@ -1681,7 +1698,13 @@ async fn execute_one_tool(
                 duration: start.elapsed(),
                 success: false,
             });
-            Ok(format!("Error executing {call_name}: {e}"))
+            let error_str = e.to_string();
+            let hint = crate::tools::error_hints::recovery_hint(call_name, &error_str);
+            if hint.is_empty() {
+                Ok(format!("Error executing {call_name}: {error_str}"))
+            } else {
+                Ok(format!("Error executing {call_name}: {error_str}\n{hint}"))
+            }
         }
     }
 }
@@ -2280,8 +2303,19 @@ pub(crate) async fn run_tool_call_loop(
     }
 
     let mut overflow_retries: usize = 0;
+    let mut consecutive_failures: std::collections::HashMap<String, usize> = std::collections::HashMap::new();
+
+    for iteration in 0..max_iterations {
+        // Notify progress for multi-iteration tool loops (skip the first iteration).
+        if iteration > 0 {
+            if let Some(ref tx) = on_tool_call {
+                let _ = tx.try_send(ToolCallNotification::Progress {
+                    iteration: iteration + 1,
+                    max_iterations,
+                });
+            }
+        }
 
-    for _iteration in 0..max_iterations {
         if cancellation_token.as_ref().is_some_and(CancellationToken::is_cancelled) {
             return Err(ToolLoopCancelled.into());
         }
@@ -2573,6 +2607,7 @@ pub(crate) async fn run_tool_call_loop(
             }
         }
 
+        let tools_started_at = Instant::now();
         let individual_results = execute_tools_with_policy(
             &tool_calls,
             tools_registry,
@@ -2584,6 +2619,7 @@ pub(crate) async fn run_tool_call_loop(
             scope_ctx,
         )
         .await?;
+        let tools_elapsed_ms = tools_started_at.elapsed().as_millis() as u64;
 
         for (call, result) in tool_calls.iter().zip(individual_results.iter()) {
             let success = !result.starts_with("Error");
@@ -2602,18 +2638,37 @@ pub(crate) async fn run_tool_call_loop(
                     .send(ToolCallNotification::Finished {
                         name: call.name.clone(),
                         success,
+                        duration_ms: tools_elapsed_ms,
                     })
                     .await;
             }
             if !success {
                 hooks.emit(HookEvent::Error, payload_error("tool", result)).await;
             }
+
+            // Track consecutive failures per tool for repeated-failure hints.
+            let repeated_hint = if success {
+                consecutive_failures.remove(&call.name);
+                String::new()
+            } else {
+                let count = consecutive_failures.entry(call.name.clone()).or_insert(0);
+                *count += 1;
+                if *count >= 2 {
+                    format!(
+                        "\n[System: tool '{}' has failed {} times consecutively. Consider a different approach or tool.]",
+                        call.name, count
+                    )
+                } else {
+                    String::new()
+                }
+            };
+
             // P0-2: Truncate oversized tool results before inserting into history.
             let truncated_result = truncate_tool_result_if_needed(result, MAX_TOOL_RESULT_CHARS);
             let _ = writeln!(
                 tool_results,
-                "<tool_result name=\"{}\">\n{}\n</tool_result>",
-                call.name, truncated_result
+                "<tool_result name=\"{}\">\n{}{}\n</tool_result>",
+                call.name, truncated_result, repeated_hint
             );
         }
 

src/agent/loop_.rs

@@ -523,12 +523,12 @@ async fn turn_handles_unknown_tool_gracefully() {
         "Expected non-empty response after unknown tool recovery"
     );
 
-    // Verify the tool result mentioned "Unknown tool"
+    // Verify the tool result mentioned "unknown tool"
     let has_tool_result = agent.history().iter().any(|msg| match msg {
-        ConversationMessage::ToolResults(results) => results.iter().any(|r| r.content.contains("Unknown tool")),
+        ConversationMessage::ToolResults(results) => results.iter().any(|r| r.content.contains("unknown tool")),
         _ => false,
     });
-    assert!(has_tool_result, "Expected tool result with 'Unknown tool' message");
+    assert!(has_tool_result, "Expected tool result with 'unknown tool' message");
 }
 
 // ═══════════════════════════════════════════════════════════════════════════

src/agent/tests.rs

@@ -2250,15 +2250,32 @@ async fn process_channel_message(
                         "Tool call started"
                     );
                 }
-                crate::agent::loop_::ToolCallNotification::Finished { name, success } => {
+                crate::agent::loop_::ToolCallNotification::Finished {
+                    name,
+                    success,
+                    duration_ms,
+                } => {
                     tracing::info!(
                         channel = %tool_event_channel_name,
                         sender = %tool_event_sender_name,
                         tool = %name,
                         success,
+                        duration_ms,
                         "Tool call finished"
                     );
                 }
+                crate::agent::loop_::ToolCallNotification::Progress {
+                    iteration,
+                    max_iterations,
+                } => {
+                    tracing::info!(
+                        channel = %tool_event_channel_name,
+                        sender = %tool_event_sender_name,
+                        iteration,
+                        max_iterations,
+                        "Tool loop progress"
+                    );
+                }
             }
         }
     });