feat: multi-provider LLM architecture (Provider trait, registry, fallback, /models redesign)

README.md

@@ -40,10 +40,37 @@ Star the repo ⭐, fork to contribute, or open an issue for feedback.
 
 → Full feature reference: [docs/GUIDE.md](docs/GUIDE.md#advanced-features)
 
+### Agent Lifecycle & Runtime
+
+| Capability | Description |
+|------------|-------------|
+| **Self-Upgrade** | Trigger an in-place upgrade: pulls from git source or downloads the latest GitHub release binary. Auto-restarts after upgrade — no SSH, no manual steps. |
+| **Model Switching** | Switch OpenRouter models at runtime via `/models`. Interactive picker lets you choose the best model per task: fast/cheap for simple queries, powerful for complex reasoning. |
+| **Soul Files** | SOUL.md (persona), AGENTS.md (behaviour), USER.md (preferences) — persistent identity files auto-injected into every system prompt. Session-end self-reflection with `.bak` backups. |
+
 ---
-| 🚀 **Self-Upgrade** | `/self-upgrade` slash command + `self_upgrade` tool, auto-restart after upgrade, git source or GitHub release binary |
-| 🔀 **Model Switching** | `/models` slash command to switch OpenRouter LLM models at runtime, with interactive model picker |
-| 📝 **Soul Files** | SOUL.md / AGENTS.md / USER.md persistent identity files, auto-injected into system prompt, session-end reflection with `.bak` backups |
+
+### 💭 Multi-Session & Multi-Model (Brainstorming)
+
+> ⚠️ **Planning phase** — not yet implemented. This section captures ideas explored in the `feat/readme-improve-multi-session-brainstorm` branch.
+
+The vision: run multiple concurrent chat sessions, each with its own model and isolated context.
+
+| Use Case | Description |
+|----------|-------------|
+| **Parallel execution** | Run a cheap model for quick tasks while a powerful model tackles deep analysis — concurrently, not sequentially |
+| **Per-user isolation** | Each Telegram user gets their own session with independent conversation context and model preference |
+| **Sub-agent delegation** | Spawn sub-agents with different models (e.g., GPT-4o for code review, Claude for writing) without polluting the main session |
+
+**Topics to explore:**
+
+- Session lifecycle — create, switch, merge, archive
+- Per-session model binding vs global default model
+- Context isolation between sessions (independent or shared RAG?)
+- Telegram UX for multi-session management (inline buttons? slash commands?)
+- Persistence and RAG across session boundaries
+
+See [docs/roadmap/multi-session.md](docs/roadmap/multi-session.md) for detailed design notes.
 
 ## Quick Start
 

config.example.toml

@@ -25,6 +25,37 @@ Use the available tools to help the user with their tasks. \
 When using file or terminal tools, operate only within the allowed sandbox directory. \
 Be concise and helpful."""
 
+# ── Multi-Provider Configuration (optional) ────────────────────────────
+# Define additional LLM providers alongside OpenRouter.
+# Each [[provider]] block adds a new provider. Model strings use the
+# format `provider_name/model_id` (e.g., `ollama/llama3.1`).
+# The first provider becomes the default.
+
+# Example: Ollama (local models)
+# [[provider]]
+# name = "ollama"
+# type = "ollama"
+# base_url = "http://localhost:11434/v1"
+# model = "llama3.1"
+# discover_models = true
+
+# Example: Any OpenAI-compatible endpoint (LM Studio, vLLM, llama.cpp, etc.)
+# [[provider]]
+# name = "lmstudio"
+# type = "openai_compatible"
+# base_url = "http://localhost:1234/v1"
+# model = "qwen2.5-7b-instruct"
+
+# ── Fallback Chain (optional) ──────────────────────────────────────────
+# When the primary model fails, RustFox tries each fallback in order.
+# Each entry is a full provider-prefixed model string.
+# [fallback]
+# chain = [
+#     "openrouter/moonshotai/kimi-k2.6",
+#     "ollama/llama3.1",
+#     "lmstudio/qwen2.5-7b-instruct",
+# ]
+
 # ── Home directory & paths ──────────────────────────────────────────────
 # By default RustFox stores everything under ~/.rustfox:
 #   ~/.rustfox/config.toml, rustfox.db, skills/, agents/, workspace/, artifacts/

docs/roadmap/multi-session-multi-model.md

@@ -0,0 +1,86 @@
+# Multi-Session & Multi-Model — Brainstorming Roadmap
+
+> ⚠️ **Planning phase** — not yet implemented. This document captures the vision, design constraints, and open questions.
+
+## Motivation
+
+Today RustFox runs a **single chat session** with **one model at a time**. You `/models` to switch, and the whole bot changes personality.
+
+But power users want:
+
+1. **Multiple concurrent sessions** — work on 3 different projects in 3 different chats, each with independent context.
+2. **Different models per session** — code review chat uses Claude Opus, casual chat uses Haiku.
+3. **Agent-to-agent delegation** (already partially solved) — one session can ask another session's model to do something.
+
+## Core Concepts
+
+### Session = Chat Thread
+
+Each Telegram chat (DM or group) is a **session**. Sessions are isolated:
+- Each has its own conversation history (context window)
+- Each can be assigned a different model
+- Each can have different system prompts / soul files
+
+### Session Model Binding
+
+| Concept | Description |
+|---------|-------------|
+| **Default model** | The model used for new sessions (from config) |
+| **Session model** | Override for a specific session via `/models` |
+| **Session stickiness** | Model choice persists across bot restarts |
+
+### Context Isolation
+
+| Aspect | Shared | Per-Session |
+|--------|--------|-------------|
+| Soul files (SOUL.md, AGENTS.md, USER.md) | ✅ | ❌ |
+| Conversation history | ❌ | ✅ |
+| Scheduled tasks | ✅ | ❌ (scheduler is global) |
+| Active model | ❌ | ✅ |
+| Plans | ❌ | ✅ (per-session plan tracking) |
+| Skills | ✅ | ❌ |
+
+## Potential Approach
+
+### Option A: Stateless Sessions
+
+- Session state lives entirely in Telegram (message history replayed on context window overflow)
+- No per-session persistence — just model binding
+- **Pros**: Simple, no new infrastructure
+- **Cons**: Context window limited to recent messages, slow startup replay
+
+### Option B: Lightweight Session Store
+
+- SQLite table `sessions (chat_id, model_name, context_summary, last_active)`
+- On each new message, load session state, inject context summary, respond
+- **Pros**: Context summaries survive restarts, faster than full replay
+- **Cons**: New persistence complexity, summary drift
+
+### Option C: Full Context Persistence
+
+- Store full conversation vector embeddings + message history in SQLite
+- RAG-style retrieval at the start of each turn
+- **Pros**: Maximum context recall
+- **Cons**: Heavy infrastructure, token cost, complexity
+
+## Open Questions
+
+1. **Session lifecycle**: When does a session "expire"? After inactivity? Never?
+2. **Cross-session memory**: Should sessions share learned facts (RLHF-style)?
+3. **SQLite schema**: How does session state compose with the existing learning/scheduler tables?
+4. **Cost tracking**: Per-session token usage & cost reporting?
+5. **Billing model**: Some users may want per-session billing (e.g., `gpt-4` costs more than `haiku`).
+6. **Migration path**: Users upgrading from single-model shouldn't lose their config.
+
+## Related Work
+
+- `invoke_agent` / `spawn_agents` — already supports subagent isolation
+- `/models` command — already supports runtime model switching
+- Soul files — already support persistent identity
+
+## Next Steps
+
+1. Choose an approach (A, B, or hybrid)
+2. Design SQLite schema if needed
+3. Scope implementation into trackable issues
+4. Plan migration path for existing users