feat: tok/s indicator + todo management — active streaming rate, no-usage fallback, auto-poke

Author: alecuba16

docs/configuration.md

@@ -42,6 +42,7 @@ values. Keys absent from the project file fall back to the global value.
   "config": { ... },
   "providers": { ... },
   "modelOverrides": { ... },
+  "favoriteModels": [ ... ],
   "projects": { ... },
   "commands": { ... },
   "formatter": { ... },
@@ -380,6 +381,69 @@ and `api_base` override the corresponding environment variables.
 | `models_blacklist` | array | These model IDs are never offered. |
 | `options` | object | Provider-specific passthrough options. |
 
+### Custom OpenAI-Compatible Providers
+
+For OpenAI-compatible endpoints not in the built-in provider list (e.g.
+self-hosted gateways, internal LLM proxies), define them under the
+`customProviders` map. Each entry is a self-contained provider with its
+own base URL, API key, custom headers, and model catalog.
+
+```json
+"customProviders": {
+  "my-gateway": {
+    "name": "My Gateway",
+    "apiBase": "https://gateway.example.com/v1",
+    "apiKey": "{env:GATEWAY_API_KEY}",
+    "headers": {
+      "X-Custom-Header": "value"
+    },
+    "models": {
+      "model-1": {
+        "name": "Model One",
+        "contextWindow": 128000,
+        "maxOutputTokens": 8192,
+        "reasoningEffort": "high",
+        "variants": {
+          "max": { "reasoningEffort": "max" },
+          "none": { "reasoningEffort": "none" }
+        }
+      }
+    },
+    "requestTimeoutSecs": 300
+  }
+}
+```
+
+`CustomProviderDef` fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Display name shown in the provider picker. |
+| `apiBase` | string | OpenAI-compatible base URL. Claurst appends `/chat/completions`. |
+| `apiKey` | string \| null | API key. Supports `{env:VAR}` substitution. `null` = no key. |
+| `headers` | object | Custom HTTP headers sent on every request. |
+| `models` | object | Model catalog local to this provider, keyed by model id. |
+| `requestTimeoutSecs` | number \| null | Per-provider request timeout override in seconds. |
+
+`CustomModelDef` fields (inside `models`):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string \| null | Display name shown in the model picker. |
+| `contextWindow` | number \| null | Total context window size in tokens. |
+| `maxOutputTokens` | number \| null | Maximum tokens the model can emit in one response. |
+| `reasoningEffort` | string \| null | Reasoning effort level (`"high"`, `"max"`, `"none"`). |
+| `variants` | object | Named variants that override specific fields. |
+
+Adding a provider via the `/add` command:
+
+```
+/add my-gateway https://gateway.example.com/v1 {env:GATEWAY_API_KEY}
+```
+
+The map key (e.g. `"my-gateway"`) becomes the provider id used in
+`provider/model` routing (e.g. `my-gateway/model-1`).
+
 ---
 
 ## Environment Variables
@@ -639,6 +703,13 @@ matches. They are defined in the `formatter` map:
     }
   },
 
+  // Pin frequently-used models to the top of the /model picker.
+  "favoriteModels": [
+    "anthropic/claude-sonnet-4-6",
+    "openai/gpt-4o",
+    "nvidia/z-ai/glm-5.2"
+  ],
+
   // Custom slash commands
   "commands": {
     "test": {
@@ -657,3 +728,29 @@ matches. They are defined in the `formatter` map:
   }
 }
 ```
+
+---
+
+## Favorite Models
+
+Pin frequently-used models to the top of the `/model` picker by adding them to
+the `favoriteModels` array in `settings.json`:
+
+```json
+"favoriteModels": [
+  "anthropic/claude-sonnet-4-6",
+  "openai/gpt-4o",
+  "nvidia/z-ai/glm-5.2"
+]
+```
+
+Entries use the canonical `"provider/model"` format (the same key used by
+`modelOverrides`). For the `anthropic` and `free` composite providers, the
+provider prefix is optional — the bare model id (`"claude-sonnet-4-6"`) is
+accepted too.
+
+In the model picker, press `f` (or `*`) to toggle favorite status on the
+highlighted model. Favorited models appear with a ★ prefix at the top of the
+list and persist across sessions in `~/.claurst/settings.json`. Stale
+favorites (models no longer in the catalog) are hidden from the picker but
+kept in settings until you un-favorite them.

src-rust/crates/api/src/model_registry.rs

@@ -1243,6 +1243,66 @@ impl ModelRegistry {
         }
         apply_overrides_to_entries(&mut self.entries, &self.overrides);
     }
+
+    /// Register user-defined custom provider models into the registry.
+    /// Each model is keyed as `<provider_id>/<model_id>` and a synthetic
+    /// `ModelEntry` is created from the `CustomModelDef` metadata.
+    /// A `ProviderEntry` is also created for each custom provider so it
+    /// appears in `/providers` listing.
+    pub fn apply_custom_providers(
+        &mut self,
+        custom_providers: &HashMap<String, claurst_core::config::CustomProviderDef>,
+    ) {
+        for (provider_id, def) in custom_providers {
+            // Register the provider entry so it shows up in /providers.
+            self.providers.entry(provider_id.clone()).or_insert(ProviderEntry {
+                id: ProviderId::new(provider_id),
+                name: def.name.clone(),
+                env: Vec::new(),
+                api: Some(def.api_base.clone()),
+                npm: None,
+                doc: None,
+            });
+
+            for (model_id, model_def) in &def.models {
+                let key = format!("{}/{}", provider_id, model_id);
+                self.entries.insert(key, ModelEntry {
+                    info: ModelInfo {
+                        id: ModelId::new(model_id),
+                        provider_id: ProviderId::new(provider_id),
+                        name: model_def.name.clone().unwrap_or_else(|| model_id.to_string()),
+                        context_window: model_def.context_window.unwrap_or(0),
+                        max_output_tokens: model_def.max_output_tokens.unwrap_or(0),
+                        release_date: None,
+                        status: None,
+                    },
+                    family: None,
+                    status: Default::default(),
+                    release_date: None,
+                    last_updated: None,
+                    knowledge: None,
+                    open_weights: false,
+                    tool_calling: true,
+                    reasoning: model_def.reasoning_effort.is_some(),
+                    structured_output: false,
+                    temperature: true,
+                    attachment: false,
+                    interleaved: None,
+                    modalities_input: vec![Modality::Text],
+                    modalities_output: vec![Modality::Text],
+                    cost_input: None,
+                    cost_output: None,
+                    cost_cache_read: None,
+                    cost_cache_write: None,
+                    cost: Default::default(),
+                    provider_override: None,
+                    experimental_modes: Default::default(),
+                    options: Default::default(),
+                    headers: Default::default(),
+                });
+            }
+        }
+    }
 }
 
 /// Layer `overrides` onto `entries`: patch existing catalog rows in place and

src-rust/crates/api/src/providers/mod.rs

@@ -1,43 +1,44 @@
-pub mod anthropic;
-pub use anthropic::AnthropicProvider;
-
-pub(crate) mod message_normalization;
-pub(crate) mod request_options;
-
-pub mod openai;
-pub use openai::OpenAiProvider;
-
-pub mod google;
-pub use google::GoogleProvider;
-
-pub mod minimax;
-pub use minimax::MinimaxProvider;
-
-pub mod openai_compat;
-pub use openai_compat::OpenAiCompatProvider;
-
-pub mod openai_compat_providers;
-pub use openai_compat_providers::{
-    baseten, cerebras, deepinfra, deepseek, fireworks, friendli, groq, huggingface, llama_cpp,
-    lm_studio, mistral, moonshot, nebius, novita, nvidia, ollama, opencode_zen, openrouter,
-    ovhcloud, perplexity, qwen, sambanova, scaleway, siliconflow, stepfun, together_ai, upstage,
-    venice, vultr_ai, xai, zai, zhipu,
-};
-
-pub mod free;
-pub use free::{catalog_entry, FreeEntry, FreeProvider, FreeUpstream, FREE_CATALOG};
-
-pub mod cohere;
-pub use cohere::CohereProvider;
-
-pub mod azure;
-pub use azure::AzureProvider;
-
-pub mod bedrock;
-pub use bedrock::BedrockProvider;
-
-pub mod copilot;
-pub use copilot::CopilotProvider;
-
-pub mod codex;
-pub use codex::CodexProvider;
+pub mod anthropic;
+pub use anthropic::AnthropicProvider;
+
+pub(crate) mod message_normalization;
+pub(crate) mod request_options;
+
+pub mod openai;
+pub use openai::OpenAiProvider;
+
+pub mod google;
+pub use google::GoogleProvider;
+
+pub mod minimax;
+pub use minimax::MinimaxProvider;
+
+pub mod openai_compat;
+pub use openai_compat::OpenAiCompatProvider;
+
+pub mod openai_compat_providers;
+pub use openai_compat_providers::{
+    baseten, cerebras, deepinfra, deepseek, fireworks, friendli, groq, huggingface, llama_cpp,
+    lm_studio, mistral, moonshot, nebius, novita, nvidia, ollama, opencode_zen, openrouter,
+    ovhcloud, perplexity, qwen, sambanova, scaleway, siliconflow, stepfun, together_ai, upstage,
+    venice, vultr_ai, xai, zai, zhipu,
+};
+
+pub mod free;
+pub use free::{catalog_entry, FreeEntry, FreeProvider, FreeUpstream, FREE_CATALOG};
+
+pub mod cohere;
+pub use cohere::CohereProvider;
+
+pub mod azure;
+pub use azure::AzureProvider;
+
+pub mod bedrock;
+pub use bedrock::BedrockProvider;
+
+pub mod copilot;
+pub use copilot::CopilotProvider;
+
+pub mod codex;
+pub use codex::CodexProvider;
+

src-rust/crates/api/src/providers/openai_compat.rs

@@ -32,8 +32,12 @@ use super::request_options::merge_openai_compatible_options;
 
 /// Provider-specific behavioural quirks that alter how the generic adapter
 /// builds and interprets requests/responses.
-#[derive(Debug, Clone, Default)]
+#[derive(Debug, Clone)]
 pub struct ProviderQuirks {
+    /// Whether this provider supports SSE streaming.  Default: `true`.
+    /// When `false`, the query engine falls back to non-streaming requests.
+    pub streaming: bool,
+
     /// Truncate tool call IDs to at most this many characters before sending.
     /// For example, Mistral requires tool IDs of at most 9 characters.
     pub tool_id_max_len: Option<usize>,
@@ -95,6 +99,26 @@ pub struct ProviderQuirks {
     pub lm_studio_native_host: Option<String>,
 }
 
+impl Default for ProviderQuirks {
+    fn default() -> Self {
+        Self {
+            streaming: true,
+            tool_id_max_len: None,
+            tool_id_alphanumeric_only: false,
+            overflow_patterns: Vec::new(),
+            include_usage_in_stream: false,
+            default_temperature: None,
+            fix_tool_user_sequence: false,
+            reasoning_field: None,
+            requires_reasoning_roundtrip: false,
+            max_tokens_cap: None,
+            no_api_key_required: false,
+            ollama_native_host: None,
+            lm_studio_native_host: None,
+        }
+    }
+}
+
 // ---------------------------------------------------------------------------
 // OpenAiCompatProvider
 // ---------------------------------------------------------------------------
@@ -1141,7 +1165,7 @@ impl LlmProvider for OpenAiCompatProvider {
 
     fn capabilities(&self) -> ProviderCapabilities {
         ProviderCapabilities {
-            streaming: true,
+            streaming: self.quirks.streaming,
             tool_calling: true,
             thinking: self.quirks.reasoning_field.is_some(),
             image_input: true,

src-rust/crates/api/src/providers/openai_compat_providers.rs

@@ -12,6 +12,10 @@ use claurst_core::provider_id::ProviderId;
 use super::openai_compat::{OpenAiCompatProvider, ProviderQuirks};
 
 pub fn provider_for_id(provider_id: &str) -> Option<OpenAiCompatProvider> {
+    // Custom providers take priority — check before the fixed-id match.
+    if let Some(custom) = provider_for_custom_id(provider_id) {
+        return Some(custom);
+    }
     match provider_id {
         "ollama" => Some(ollama()),
         "lmstudio" | "lm-studio" => Some(lm_studio()),
@@ -164,6 +168,36 @@ pub fn custom_openai() -> OpenAiCompatProvider {
     custom_openai_with_url(base_url)
 }
 
+/// Build an [`OpenAiCompatProvider`] from a user-defined custom provider in
+/// `Settings::custom_providers`, looked up by id.
+///
+/// Returns `None` when the id is not in the custom providers map, or when
+/// `apiBase` is empty. Custom headers from the definition are applied via
+/// the builder API. API key is resolved via `resolve_api_key()` (supports
+/// `{env:VAR}` substitution).
+pub fn provider_for_custom_id(id: &str) -> Option<OpenAiCompatProvider> {
+    let settings = Settings::load_sync().unwrap_or_default();
+    let def = settings.custom_providers.get(id)?;
+    if def.api_base.trim().is_empty() {
+        return None;
+    }
+    let mut provider = OpenAiCompatProvider::new(id, &def.name, &def.api_base);
+    if let Some(key) = def.resolve_api_key() {
+        provider = provider.with_api_key(key);
+    }
+    for (name, value) in &def.headers {
+        provider = provider.with_header(name, value);
+    }
+    // Apply streaming / reasoning settings from the custom provider definition.
+    provider = provider.with_quirks(ProviderQuirks {
+        streaming: def.streaming.unwrap_or(true),
+        include_usage_in_stream: def.include_usage_in_stream.unwrap_or(true),
+        reasoning_field: def.reasoning_field.clone(),
+        ..Default::default()
+    });
+    Some(provider)
+}
+
 /// DeepSeek V4 — supports reasoning output via `reasoning_content` field.
 /// V4 models require reasoning_content to be echoed back on subsequent turns
 /// in multi-turn conversations with tool calls.
@@ -630,4 +664,19 @@ mod tests {
         assert_eq!(alibaba.id(), qwen.id());
         assert_eq!(alibaba.name(), qwen.name());
     }
+
+    #[test]
+    fn provider_for_custom_id_returns_none_for_unknown() {
+        // "nonexistent-custom-provider-12345" is not a real custom provider.
+        assert!(provider_for_custom_id("nonexistent-custom-provider-12345").is_none());
+    }
+
+    #[test]
+    fn provider_for_custom_id_returns_none_for_known_fixed_provider() {
+        // Fixed providers like "ollama" should not match as custom providers.
+        // This test verifies that provider_for_custom_id doesn't accidentally
+        // return Some for a fixed provider id when no custom provider is
+        // registered with that id.
+        assert!(provider_for_custom_id("ollama").is_none());
+    }
 }