Initial import of Claude_Code

Claude_Code/.dockerignore

@@ -0,0 +1,8 @@
+.git
+.venv
+__pycache__
+*.pyc
+.env
+uv.lock
+nvidia_nim_models.json
+pic.png

Claude_Code/.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

Claude_Code/.gitignore

@@ -0,0 +1,12 @@
+__pycache__
+.claude
+.cursor
+.pytest_cache
+.ruff_cache
+.serena
+.venv
+agent_workspace
+.env
+server.log
+.coverage
+llama_cache

Claude_Code/.python-version

@@ -0,0 +1 @@
+3.14.0

Claude_Code/AGENTS.md

@@ -0,0 +1,52 @@
+# AGENTIC DIRECTIVE
+
+> This file is identical to CLAUDE.md. Keep them in sync.
+
+## CODING ENVIRONMENT
+
+- Install astral uv using "curl -LsSf https://astral.sh/uv/install.sh | sh" if not already installed and if already installed then update it to the latest version
+- Install Python 3.14 using `uv python install 3.14` if not already installed
+- Always use `uv run` to run files instead of the global `python` command.
+- Current uv ruff formatter is set to py314 which has supports multiple exception types without paranthesis (except TypeError, ValueError:)
+- Read `.env.example` for environment variables.
+- All CI checks must pass; failing checks block merge.
+- Add tests for new changes (including edge cases), then run `uv run pytest`.
+- Run checks in this order: `uv run ruff format`, `uv run ruff check`, `uv run ty check`, `uv run pytest`.
+- Do not add `# type: ignore` or `# ty: ignore`; fix the underlying type issue.
+- All 5 checks are enforced in `tests.yml` on push/merge.
+
+## IDENTITY & CONTEXT
+
+- You are an expert Software Architect and Systems Engineer.
+- Goal: Zero-defect, root-cause-oriented engineering for bugs; test-driven engineering for new features. Think carefully; no need to rush.
+- Code: Write the simplest code possible. Keep the codebase minimal and modular.
+
+## ARCHITECTURE PRINCIPLES (see PLAN.md)
+
+- **Shared utilities**: Extract common logic into shared packages (e.g. `providers/common/`). Do not have one provider import from another provider's utils.
+- **DRY**: Extract shared base classes to eliminate duplication. Prefer composition over copy-paste.
+- **Encapsulation**: Use accessor methods for internal state (e.g. `set_current_task()`), not direct `_attribute` assignment from outside.
+- **Provider-specific config**: Keep provider-specific fields (e.g. `nim_settings`) in provider constructors, not in the base `ProviderConfig`.
+- **Dead code**: Remove unused code, legacy systems, and hardcoded values. Use settings/config instead of literals (e.g. `settings.provider_type` not `"nvidia_nim"`).
+- **Performance**: Use list accumulation for strings (not `+=` in loops), cache env vars at init, prefer iterative over recursive when stack depth matters.
+- **Platform-agnostic naming**: Use generic names (e.g. `PLATFORM_EDIT`) not platform-specific ones (e.g. `TELEGRAM_EDIT`) in shared code.
+- **No type ignores**: Do not add `# type: ignore` or `# ty: ignore`. Fix the underlying type issue.
+- **Backward compatibility**: When moving modules, add re-exports from old locations so existing imports keep working.
+
+## COGNITIVE WORKFLOW
+
+1. **ANALYZE**: Read relevant files. Do not guess.
+2. **PLAN**: Map out the logic. Identify root cause or required changes. Order changes by dependency.
+3. **EXECUTE**: Fix the cause, not the symptom. Execute incrementally with clear commits.
+4. **VERIFY**: Run ci checks. Confirm the fix via logs or output.
+5. **SPECIFICITY**: Do exactly as much as asked; nothing more, nothing less.
+6. **PROPAGATION**: Changes impact multiple files; propagate updates correctly.
+
+## SUMMARY STANDARDS
+
+- Summaries must be technical and granular.
+- Include: [Files Changed], [Logic Altered], [Verification Method], [Residual Risks] (if no residual risks then say none).
+
+## TOOLS
+
+- Prefer built-in tools (grep, read_file, etc.) over manual workflows. Check tool availability before use.

Claude_Code/CLAUDE.md

@@ -0,0 +1 @@
+IMPORTANT: Ensure you’ve thoroughly reviewed the [AGENTS.md](AGENTS.md) file before beginning any work.

Claude_Code/Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+ENV PYTHONUNBUFFERED=1
+
+# Install uv for faster dependency installation
+RUN pip install --no-cache-dir uv
+
+# Install dependencies
+COPY requirements.txt .
+RUN uv pip install --system --no-cache-dir -r requirements.txt
+
+# Copy application source code
+COPY . .
+
+EXPOSE 7860
+
+CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "7860"]

Claude_Code/README.md

@@ -0,0 +1,588 @@
+---
+title: Claude Code
+emoji: 🤖
+colorFrom: indigo
+colorTo: blue
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+<div align="center">
+
+# 🤖 Free Claude Code
+
+### Use Claude Code CLI & VSCode for free. No Anthropic API key required.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
+[![Python 3.12](https://img.shields.io/badge/python-3.12-3776ab.svg?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json&style=for-the-badge)](https://github.com/astral-sh/uv)
+[![Tested with Pytest](https://img.shields.io/badge/testing-Pytest-00c0ff.svg?style=for-the-badge)](https://github.com/Alishahryar1/free-claude-code/actions/workflows/tests.yml)
+[![Type checking: Ty](https://img.shields.io/badge/type%20checking-ty-ffcc00.svg?style=for-the-badge)](https://pypi.org/project/ty/)
+[![Code style: Ruff](https://img.shields.io/badge/code%20formatting-ruff-f5a623.svg?style=for-the-badge)](https://github.com/astral-sh/ruff)
+[![Logging: Loguru](https://img.shields.io/badge/logging-loguru-4ecdc4.svg?style=for-the-badge)](https://github.com/Delgan/loguru)
+
+A lightweight proxy that routes Claude Code's Anthropic API calls to **NVIDIA NIM** (40 req/min free), **OpenRouter** (hundreds of models), **LM Studio** (fully local), or **llama.cpp** (local with Anthropic endpoints).
+
+[Quick Start](#quick-start) · [Providers](#providers) · [Discord Bot](#discord-bot) · [Configuration](#configuration) · [Development](#development) · [Contributing](#contributing)
+
+---
+
+</div>
+
+<div align="center">
+  <img src="pic.png" alt="Free Claude Code in action" width="700">
+  <p><em>Claude Code running via NVIDIA NIM, completely free</em></p>
+</div>
+
+## Features
+
+| Feature                    | Description                                                                                     |
+| -------------------------- | ----------------------------------------------------------------------------------------------- |
+| **Zero Cost**              | 40 req/min free on NVIDIA NIM. Free models on OpenRouter. Fully local with LM Studio            |
+| **Drop-in Replacement**    | Set 2 env vars. No modifications to Claude Code CLI or VSCode extension needed                  |
+| **4 Providers**            | NVIDIA NIM, OpenRouter (hundreds of models), LM Studio (local), llama.cpp (`llama-server`)      |
+| **Per-Model Mapping**      | Route Opus / Sonnet / Haiku to different models and providers. Mix providers freely             |
+| **Thinking Token Support** | Parses `<think>` tags and `reasoning_content` into native Claude thinking blocks                |
+| **Heuristic Tool Parser**  | Models outputting tool calls as text are auto-parsed into structured tool use                   |
+| **Request Optimization**   | 5 categories of trivial API calls intercepted locally, saving quota and latency                 |
+| **Smart Rate Limiting**    | Proactive rolling-window throttle + reactive 429 exponential backoff + optional concurrency cap |
+| **Discord / Telegram Bot** | Remote autonomous coding with tree-based threading, session persistence, and live progress      |
+| **Subagent Control**       | Task tool interception forces `run_in_background=False`. No runaway subagents                   |
+| **Extensible**             | Clean `BaseProvider` and `MessagingPlatform` ABCs. Add new providers or platforms easily        |
+
+## Quick Start
+
+### Prerequisites
+
+1. Get an API key (or use LM Studio / llama.cpp locally):
+   - **NVIDIA NIM**: [build.nvidia.com/settings/api-keys](https://build.nvidia.com/settings/api-keys)
+   - **OpenRouter**: [openrouter.ai/keys](https://openrouter.ai/keys)
+   - **LM Studio**: No API key needed. Run locally with [LM Studio](https://lmstudio.ai)
+   - **llama.cpp**: No API key needed. Run `llama-server` locally.
+2. Install [Claude Code](https://github.com/anthropics/claude-code)
+3. Install [uv](https://github.com/astral-sh/uv) (or `uv self update` if already installed)
+
+### Clone & Configure
+
+```bash
+git clone https://github.com/Alishahryar1/free-claude-code.git
+cd free-claude-code
+cp .env.example .env
+```
+
+Choose your provider and edit `.env`:
+
+<details>
+<summary><b>NVIDIA NIM</b> (40 req/min free, recommended)</summary>
+
+```dotenv
+NVIDIA_NIM_API_KEY="nvapi-your-key-here"
+
+MODEL_OPUS="nvidia_nim/z-ai/glm4.7"
+MODEL_SONNET="nvidia_nim/moonshotai/kimi-k2-thinking"
+MODEL_HAIKU="nvidia_nim/stepfun-ai/step-3.5-flash"
+MODEL="nvidia_nim/z-ai/glm4.7"                     # fallback
+
+# Enable for thinking models (kimi, nemotron). Leave false for others (e.g. Mistral).
+NIM_ENABLE_THINKING=true
+```
+
+</details>
+
+<details>
+<summary><b>OpenRouter</b> (hundreds of models)</summary>
+
+```dotenv
+OPENROUTER_API_KEY="sk-or-your-key-here"
+
+MODEL_OPUS="open_router/deepseek/deepseek-r1-0528:free"
+MODEL_SONNET="open_router/openai/gpt-oss-120b:free"
+MODEL_HAIKU="open_router/stepfun/step-3.5-flash:free"
+MODEL="open_router/stepfun/step-3.5-flash:free"     # fallback
+```
+
+</details>
+
+<details>
+<summary><b>LM Studio</b> (fully local, no API key)</summary>
+
+```dotenv
+MODEL_OPUS="lmstudio/unsloth/MiniMax-M2.5-GGUF"
+MODEL_SONNET="lmstudio/unsloth/Qwen3.5-35B-A3B-GGUF"
+MODEL_HAIKU="lmstudio/unsloth/GLM-4.7-Flash-GGUF"
+MODEL="lmstudio/unsloth/GLM-4.7-Flash-GGUF"         # fallback
+```
+
+</details>
+
+<details>
+<summary><b>llama.cpp</b> (fully local, no API key)</summary>
+
+```dotenv
+LLAMACPP_BASE_URL="http://localhost:8080/v1"
+
+MODEL_OPUS="llamacpp/local-model"
+MODEL_SONNET="llamacpp/local-model"
+MODEL_HAIKU="llamacpp/local-model"
+MODEL="llamacpp/local-model"
+```
+
+</details>
+
+<details>
+<summary><b>Mix providers</b></summary>
+
+Each `MODEL_*` variable can use a different provider. `MODEL` is the fallback for unrecognized Claude models.
+
+```dotenv
+NVIDIA_NIM_API_KEY="nvapi-your-key-here"
+OPENROUTER_API_KEY="sk-or-your-key-here"
+
+MODEL_OPUS="nvidia_nim/moonshotai/kimi-k2.5"
+MODEL_SONNET="open_router/deepseek/deepseek-r1-0528:free"
+MODEL_HAIKU="lmstudio/unsloth/GLM-4.7-Flash-GGUF"
+MODEL="nvidia_nim/z-ai/glm4.7"                      # fallback
+```
+
+</details>
+
+<details>
+<summary><b>Optional Authentication</b> (restrict access to your proxy)</summary>
+
+Set `ANTHROPIC_AUTH_TOKEN` in `.env` to require clients to authenticate:
+
+```dotenv
+ANTHROPIC_AUTH_TOKEN="your-secret-token-here"
+```
+
+**How it works:**
+- If `ANTHROPIC_AUTH_TOKEN` is empty (default), no authentication is required (backward compatible)
+- If set, clients must provide the same token via the `ANTHROPIC_AUTH_TOKEN` header
+- For private Hugging Face Spaces, query auth is supported as `?psw=token`, `?psw:token`, or `?psw%3Atoken`
+- The `claude-pick` script automatically reads the token from `.env` if configured
+
+**Example usage:**
+```bash
+# With authentication
+ANTHROPIC_AUTH_TOKEN="your-secret-token-here" \
+ANTHROPIC_BASE_URL="http://localhost:8082" claude
+
+# Hugging Face private Space (query auth in URL)
+ANTHROPIC_API_KEY="Jack@188" \
+ANTHROPIC_BASE_URL="https://<your-space>.hf.space?psw:Jack%40188" claude
+
+# claude-pick automatically uses the configured token
+claude-pick
+```
+
+Note: `HEAD /` returning `405 Method Not Allowed` means auth already passed; only `GET /` is implemented.
+
+Use this feature if:
+- Running the proxy on a public network
+- Sharing the server with others but restricting access
+- Wanting an additional layer of security
+
+</details>
+
+### Run It
+
+**Terminal 1:** Start the proxy server:
+
+```bash
+uv run uvicorn server:app --host 0.0.0.0 --port 8082
+```
+
+**Terminal 2:** Run Claude Code:
+
+#### Powershell
+```powershell
+$env:ANTHROPIC_BASE_URL="http://localhost:8082?psw:Jack%40188"; $env:ANTHROPIC_API_KEY="Jack@188"; claude
+```
+#### Bash
+```bash
+export ANTHROPIC_BASE_URL="http://localhost:8082?psw:Jack%40188"; export ANTHROPIC_API_KEY="Jack@188"; claude
+```
+
+That's it! Claude Code now uses your configured provider for free.
+
+### One-Click Factory Reset (Space Admin)
+
+Open the admin page:
+
+- Local: `http://localhost:8082/admin/factory-reset?psw:Jack%40188`
+- Space: `https://<your-space>.hf.space/admin/factory-reset?psw:Jack%40188`
+
+Click **Factory Restart** to clear runtime cache + workspace data and restart the server.
+
+<details>
+<summary><b>VSCode Extension Setup</b></summary>
+
+1. Start the proxy server (same as above).
+2. Open Settings (`Ctrl + ,`) and search for `claude-code.environmentVariables`.
+3. Click **Edit in settings.json** and add:
+
+```json
+"claudeCode.environmentVariables": [
+  { "name": "ANTHROPIC_BASE_URL", "value": "http://localhost:8082" },
+  { "name": "ANTHROPIC_AUTH_TOKEN", "value": "freecc" }
+]
+```
+
+4. Reload extensions.
+5. **If you see the login screen**: Click **Anthropic Console**, then authorize. The extension will start working. You may be redirected to buy credits in the browser; ignore it — the extension already works.
+
+To switch back to Anthropic models, comment out the added block and reload extensions.
+
+</details>
+
+<details>
+<summary><b>Multi-Model Support (Model Picker)</b></summary>
+
+`claude-pick` is an interactive model selector that lets you choose any model from your active provider each time you launch Claude, without editing `MODEL` in `.env`.
+
+https://github.com/user-attachments/assets/9a33c316-90f8-4418-9650-97e7d33ad645
+
+**1. Install [fzf](https://github.com/junegunn/fzf)**:
+
+```bash
+brew install fzf        # macOS/Linux
+```
+
+**2. Add the alias to `~/.zshrc` or `~/.bashrc`:**
+
+```bash
+alias claude-pick="/absolute/path/to/free-claude-code/claude-pick"
+```
+
+Then reload your shell (`source ~/.zshrc` or `source ~/.bashrc`) and run `claude-pick`.
+
+**Or use a fixed model alias** (no picker needed):
+
+```bash
+alias claude-kimi='ANTHROPIC_BASE_URL="http://localhost:8082" ANTHROPIC_AUTH_TOKEN="freecc:moonshotai/kimi-k2.5" claude'
+```
+
+</details>
+
+### Install as a Package (no clone needed)
+
+```bash
+uv tool install git+https://github.com/Alishahryar1/free-claude-code.git
+fcc-init        # creates ~/.config/free-claude-code/.env from the built-in template
+```
+
+Edit `~/.config/free-claude-code/.env` with your API keys and model names, then:
+
+```bash
+free-claude-code    # starts the server
+```
+
+> To update: `uv tool upgrade free-claude-code`
+
+---
+
+## How It Works
+
+```
+┌─────────────────┐        ┌──────────────────────┐        ┌──────────────────┐
+│  Claude Code    │───────>│  Free Claude Code    │───────>│  LLM Provider    │
+│  CLI / VSCode   │<───────│  Proxy (:8082)       │<───────│  NIM / OR / LMS  │
+└─────────────────┘        └──────────────────────┘        └──────────────────┘
+   Anthropic API                                             OpenAI-compatible
+   format (SSE)                                             format (SSE)
+```
+
+- **Transparent proxy**: Claude Code sends standard Anthropic API requests; the proxy forwards them to your configured provider
+- **Per-model routing**: Opus / Sonnet / Haiku requests resolve to their model-specific backend, with `MODEL` as fallback
+- **Request optimization**: 5 categories of trivial requests (quota probes, title generation, prefix detection, suggestions, filepath extraction) are intercepted and responded to locally without using API quota
+- **Format translation**: Requests are translated from Anthropic format to the provider's OpenAI-compatible format and streamed back
+- **Thinking tokens**: `<think>` tags and `reasoning_content` fields are converted into native Claude thinking blocks
+
+---
+
+## Providers
+
+| Provider       | Cost         | Rate Limit | Best For                             |
+| -------------- | ------------ | ---------- | ------------------------------------ |
+| **NVIDIA NIM** | Free         | 40 req/min | Daily driver, generous free tier     |
+| **OpenRouter** | Free / Paid  | Varies     | Model variety, fallback options      |
+| **LM Studio**  | Free (local) | Unlimited  | Privacy, offline use, no rate limits |
+| **llama.cpp**  | Free (local) | Unlimited  | Lightweight local inference engine   |
+
+Models use a prefix format: `provider_prefix/model/name`. An invalid prefix causes an error.
+
+| Provider   | `MODEL` prefix    | API Key Variable     | Default Base URL              |
+| ---------- | ----------------- | -------------------- | ----------------------------- |
+| NVIDIA NIM | `nvidia_nim/...`  | `NVIDIA_NIM_API_KEY` | `integrate.api.nvidia.com/v1` |
+| OpenRouter | `open_router/...` | `OPENROUTER_API_KEY` | `openrouter.ai/api/v1`        |
+| LM Studio  | `lmstudio/...`    | (none)               | `localhost:1234/v1`           |
+| llama.cpp  | `llamacpp/...`    | (none)               | `localhost:8080/v1`           |
+
+<details>
+<summary><b>NVIDIA NIM models</b></summary>
+
+Popular models (full list in [`nvidia_nim_models.json`](nvidia_nim_models.json)):
+
+- `nvidia_nim/minimaxai/minimax-m2.5`
+- `nvidia_nim/qwen/qwen3.5-397b-a17b`
+- `nvidia_nim/z-ai/glm5`
+- `nvidia_nim/moonshotai/kimi-k2.5`
+- `nvidia_nim/stepfun-ai/step-3.5-flash`
+
+Browse: [build.nvidia.com](https://build.nvidia.com/explore/discover) · Update list: `curl "https://integrate.api.nvidia.com/v1/models" > nvidia_nim_models.json`
+
+</details>
+
+<details>
+<summary><b>OpenRouter models</b></summary>
+
+Popular free models:
+
+- `open_router/arcee-ai/trinity-large-preview:free`
+- `open_router/stepfun/step-3.5-flash:free`
+- `open_router/deepseek/deepseek-r1-0528:free`
+- `open_router/openai/gpt-oss-120b:free`
+
+Browse: [openrouter.ai/models](https://openrouter.ai/models) · [Free models](https://openrouter.ai/collections/free-models)
+
+</details>
+
+<details>
+<summary><b>LM Studio models</b></summary>
+
+Run models locally with [LM Studio](https://lmstudio.ai). Load a model in the Chat or Developer tab, then set `MODEL` to its identifier.
+
+Examples with native tool-use support:
+
+- `LiquidAI/LFM2-24B-A2B-GGUF`
+- `unsloth/MiniMax-M2.5-GGUF`
+- `unsloth/GLM-4.7-Flash-GGUF`
+- `unsloth/Qwen3.5-35B-A3B-GGUF`
+
+Browse: [model.lmstudio.ai](https://model.lmstudio.ai)
+
+</details>
+
+<details>
+<summary><b>llama.cpp models</b></summary>
+
+Run models locally using `llama-server`. Ensure you have a tool-capable GGUF. Set `MODEL` to whatever arbitrary name you'd like (e.g. `llamacpp/my-model`), as `llama-server` ignores the model name when run via `/v1/messages`.
+
+See the Unsloth docs for detailed instructions and capable models:
+[https://unsloth.ai/docs/models/qwen3.5#qwen3.5-small-0.8b-2b-4b-9b](https://unsloth.ai/docs/models/qwen3.5#qwen3.5-small-0.8b-2b-4b-9b)
+
+</details>
+
+---
+
+## Discord Bot
+
+Control Claude Code remotely from Discord (or Telegram). Send tasks, watch live progress, and manage multiple concurrent sessions.
+
+**Capabilities:**
+
+- Tree-based message threading: reply to a message to fork the conversation
+- Session persistence across server restarts
+- Live streaming of thinking tokens, tool calls, and results
+- Unlimited concurrent Claude CLI sessions (concurrency controlled by `PROVIDER_MAX_CONCURRENCY`)
+- Voice notes: send voice messages; they are transcribed and processed as regular prompts
+- Commands: `/stop` (cancel a task; reply to a message to stop only that task), `/clear` (reset all sessions, or reply to clear a branch), `/stats`
+
+### Setup
+
+1. **Create a Discord Bot**: Go to [Discord Developer Portal](https://discord.com/developers/applications), create an application, add a bot, and copy the token. Enable **Message Content Intent** under Bot settings.
+
+2. **Edit `.env`:**
+
+```dotenv
+MESSAGING_PLATFORM="discord"
+DISCORD_BOT_TOKEN="your_discord_bot_token"
+ALLOWED_DISCORD_CHANNELS="123456789,987654321"
+```
+
+> Enable Developer Mode in Discord (Settings → Advanced), then right-click a channel and "Copy ID". Comma-separate multiple channels. If empty, no channels are allowed.
+
+3. **Configure the workspace** (where Claude will operate):
+
+```dotenv
+CLAUDE_WORKSPACE="./agent_workspace"
+ALLOWED_DIR="C:/Users/yourname/projects"
+```
+
+4. **Start the server:**
+
+```bash
+uv run uvicorn server:app --host 0.0.0.0 --port 8082
+```
+
+5. **Invite the bot** via OAuth2 URL Generator (scopes: `bot`, permissions: Read Messages, Send Messages, Manage Messages, Read Message History).
+
+### Telegram
+
+Set `MESSAGING_PLATFORM=telegram` and configure:
+
+```dotenv
+TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrSTUvwxYZ"
+ALLOWED_TELEGRAM_USER_ID="your_telegram_user_id"
+```
+
+Get a token from [@BotFather](https://t.me/BotFather); find your user ID via [@userinfobot](https://t.me/userinfobot).
+
+### Voice Notes
+
+Send voice messages on Discord or Telegram; they are transcribed and processed as regular prompts.
+
+| Backend                     | Description                                                                                                   | API Key              |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------- |
+| **Local Whisper** (default) | [Hugging Face Whisper](https://huggingface.co/openai/whisper-large-v3-turbo) — free, offline, CUDA compatible | not required         |
+| **NVIDIA NIM**              | Whisper/Parakeet models via gRPC                                                                              | `NVIDIA_NIM_API_KEY` |
+
+**Install the voice extras:**
+
+```bash
+# If you cloned the repo:
+uv sync --extra voice_local          # Local Whisper
+uv sync --extra voice                # NVIDIA NIM
+uv sync --extra voice --extra voice_local  # Both
+
+# If you installed as a package (no clone):
+uv tool install "free-claude-code[voice_local] @ git+https://github.com/Alishahryar1/free-claude-code.git"
+uv tool install "free-claude-code[voice] @ git+https://github.com/Alishahryar1/free-claude-code.git"
+uv tool install "free-claude-code[voice,voice_local] @ git+https://github.com/Alishahryar1/free-claude-code.git"
+```
+
+Configure via `WHISPER_DEVICE` (`cpu` | `cuda` | `nvidia_nim`) and `WHISPER_MODEL`. See the [Configuration](#configuration) table for all voice variables and supported model values.
+
+---
+
+## Configuration
+
+### Core
+
+| Variable             | Description                                                           | Default                                           |
+| -------------------- | --------------------------------------------------------------------- | ------------------------------------------------- |
+| `MODEL`              | Fallback model (`provider/model/name` format; invalid prefix → error) | `nvidia_nim/stepfun-ai/step-3.5-flash`            |
+| `MODEL_OPUS`         | Model for Claude Opus requests (falls back to `MODEL`)                | `nvidia_nim/z-ai/glm4.7`                          |
+| `MODEL_SONNET`       | Model for Claude Sonnet requests (falls back to `MODEL`)              | `open_router/arcee-ai/trinity-large-preview:free` |
+| `MODEL_HAIKU`        | Model for Claude Haiku requests (falls back to `MODEL`)               | `open_router/stepfun/step-3.5-flash:free`         |
+| `NVIDIA_NIM_API_KEY`    | NVIDIA API key                                                        | required for NIM                                  |
+| `NIM_ENABLE_THINKING`   | Send `chat_template_kwargs` + `reasoning_budget` on NIM requests. Enable for thinking models (kimi, nemotron); leave `false` for others (e.g. Mistral) | `false` |
+| `OPENROUTER_API_KEY` | OpenRouter API key                                                    | required for OpenRouter                           |
+| `LM_STUDIO_BASE_URL` | LM Studio server URL                                                  | `http://localhost:1234/v1`                        |
+| `LLAMACPP_BASE_URL`  | llama.cpp server URL                                                  | `http://localhost:8080/v1`                        |
+
+### Rate Limiting & Timeouts
+
+| Variable                   | Description                               | Default |
+| -------------------------- | ----------------------------------------- | ------- |
+| `PROVIDER_RATE_LIMIT`      | LLM API requests per window               | `40`    |
+| `PROVIDER_RATE_WINDOW`     | Rate limit window (seconds)               | `60`    |
+| `PROVIDER_MAX_CONCURRENCY` | Max simultaneous open provider streams    | `5`     |
+| `HTTP_READ_TIMEOUT`        | Read timeout for provider requests (s)    | `120`   |
+| `HTTP_WRITE_TIMEOUT`       | Write timeout for provider requests (s)   | `10`    |
+| `HTTP_CONNECT_TIMEOUT`     | Connect timeout for provider requests (s) | `2`     |
+
+### Messaging & Voice
+
+| Variable                   | Description                                                                                                                                                        | Default             |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- |
+| `MESSAGING_PLATFORM`       | `discord` or `telegram`                                                                                                                                            | `discord`           |
+| `DISCORD_BOT_TOKEN`        | Discord bot token                                                                                                                                                  | `""`                |
+| `ALLOWED_DISCORD_CHANNELS` | Comma-separated channel IDs (empty = none allowed)                                                                                                                 | `""`                |
+| `TELEGRAM_BOT_TOKEN`       | Telegram bot token                                                                                                                                                 | `""`                |
+| `ALLOWED_TELEGRAM_USER_ID` | Allowed Telegram user ID                                                                                                                                           | `""`                |
+| `CLAUDE_WORKSPACE`         | Directory where the agent operates                                                                                                                                 | `./agent_workspace` |
+| `ALLOWED_DIR`              | Allowed directories for the agent                                                                                                                                  | `""`                |
+| `MESSAGING_RATE_LIMIT`     | Messaging messages per window                                                                                                                                      | `1`                 |
+| `MESSAGING_RATE_WINDOW`    | Messaging window (seconds)                                                                                                                                         | `1`                 |
+| `VOICE_NOTE_ENABLED`       | Enable voice note handling                                                                                                                                         | `true`              |
+| `WHISPER_DEVICE`           | `cpu` \| `cuda` \| `nvidia_nim`                                                                                                                                    | `cpu`               |
+| `WHISPER_MODEL`            | Whisper model (local: `tiny`/`base`/`small`/`medium`/`large-v2`/`large-v3`/`large-v3-turbo`; NIM: `openai/whisper-large-v3`, `nvidia/parakeet-ctc-1.1b-asr`, etc.) | `base`              |
+| `HF_TOKEN`                 | Hugging Face token for faster downloads (local Whisper, optional)                                                                                                  | —                   |
+
+<details>
+<summary><b>Advanced: Request optimization flags</b></summary>
+
+These are enabled by default and intercept trivial Claude Code requests locally to save API quota.
+
+| Variable                          | Description                    | Default |
+| --------------------------------- | ------------------------------ | ------- |
+| `FAST_PREFIX_DETECTION`           | Enable fast prefix detection   | `true`  |
+| `ENABLE_NETWORK_PROBE_MOCK`       | Mock network probe requests    | `true`  |
+| `ENABLE_TITLE_GENERATION_SKIP`    | Skip title generation requests | `true`  |
+| `ENABLE_SUGGESTION_MODE_SKIP`     | Skip suggestion mode requests  | `true`  |
+| `ENABLE_FILEPATH_EXTRACTION_MOCK` | Mock filepath extraction       | `true`  |
+
+</details>
+
+See [`.env.example`](.env.example) for all supported parameters.
+
+---
+
+## Development
+
+### Project Structure
+
+```
+free-claude-code/
+├── server.py              # Entry point
+├── api/                   # FastAPI routes, request detection, optimization handlers
+├── providers/             # BaseProvider, OpenAICompatibleProvider, NIM, OpenRouter, LM Studio, llamacpp
+│   └── common/            # Shared utils (SSE builder, message converter, parsers, error mapping)
+├── messaging/             # MessagingPlatform ABC + Discord/Telegram bots, session management
+├── config/                # Settings, NIM config, logging
+├── cli/                   # CLI session and process management
+└── tests/                 # Pytest test suite
+```
+
+### Commands
+
+```bash
+uv run ruff format     # Format code
+uv run ruff check      # Lint
+uv run ty check        # Type checking
+uv run pytest          # Run tests
+```
+
+### Extending
+
+**Adding an OpenAI-compatible provider** (Groq, Together AI, etc.) — extend `OpenAICompatibleProvider`:
+
+```python
+from providers.openai_compat import OpenAICompatibleProvider
+from providers.base import ProviderConfig
+
+class MyProvider(OpenAICompatibleProvider):
+    def __init__(self, config: ProviderConfig):
+        super().__init__(config, provider_name="MYPROVIDER",
+                         base_url="https://api.example.com/v1", api_key=config.api_key)
+```
+
+**Adding a fully custom provider** — extend `BaseProvider` directly and implement `stream_response()`.
+
+**Adding a messaging platform** — extend `MessagingPlatform` in `messaging/` and implement `start()`, `stop()`, `send_message()`, `edit_message()`, and `on_message()`.
+
+---
+
+## Contributing
+
+- Report bugs or suggest features via [Issues](https://github.com/Alishahryar1/free-claude-code/issues)
+- Add new LLM providers (Groq, Together AI, etc.)
+- Add new messaging platforms (Slack, etc.)
+- Improve test coverage
+- Not accepting Docker integration PRs for now
+
+```bash
+git checkout -b my-feature
+uv run ruff format && uv run ruff check && uv run ty check && uv run pytest
+# Open a pull request
+```
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+Built with [FastAPI](https://fastapi.tiangolo.com/), [OpenAI Python SDK](https://github.com/openai/openai-python), [discord.py](https://github.com/Rapptz/discord.py), and [python-telegram-bot](https://python-telegram-bot.org/).

Claude_Code/api/__init__.py

@@ -0,0 +1,21 @@
+"""API layer for Claude Code Proxy."""
+
+from .app import app, create_app
+from .dependencies import get_provider, get_provider_for_type
+from .models import (
+    MessagesRequest,
+    MessagesResponse,
+    TokenCountRequest,
+    TokenCountResponse,
+)
+
+__all__ = [
+    "MessagesRequest",
+    "MessagesResponse",
+    "TokenCountRequest",
+    "TokenCountResponse",
+    "app",
+    "create_app",
+    "get_provider",
+    "get_provider_for_type",
+]

Claude_Code/api/app.py

@@ -0,0 +1,273 @@
+"""FastAPI application factory and configuration."""
+
+import asyncio
+import os
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import JSONResponse
+from loguru import logger
+
+from config.logging_config import configure_logging
+from config.settings import get_settings
+from providers.exceptions import ProviderError
+
+from .dependencies import cleanup_provider, validate_request_api_key
+from .routes import router
+
+# Opt-in to future behavior for python-telegram-bot
+os.environ["PTB_TIMEDELTA"] = "1"
+
+# Configure logging first (before any module logs)
+_settings = get_settings()
+configure_logging(_settings.log_file)
+
+
+_SHUTDOWN_TIMEOUT_S = 5.0
+
+
+def _normalize_malformed_query_base_url_request(request: Request) -> None:
+    """Normalize malformed request targets when base URL contains query auth.
+
+    Some clients concatenate paths onto a base URL containing query params as plain
+    strings, producing targets like:
+      /?psw:token/v1/messages?beta=true
+    This rewrites them to:
+      /v1/messages?psw:token&beta=true
+    """
+    if request.scope.get("path") != "/":
+        return
+
+    raw_query_bytes = request.scope.get("query_string", b"")
+    raw_query = raw_query_bytes.decode("utf-8", errors="ignore")
+    if not raw_query or "/v1/" not in raw_query:
+        return
+
+    auth_part, _, remainder = raw_query.partition("/v1/")
+    if not auth_part or not remainder:
+        return
+
+    if "?" in remainder:
+        path_suffix, trailing_query = remainder.split("?", 1)
+    else:
+        path_suffix, trailing_query = remainder, ""
+
+    new_path = f"/v1/{path_suffix}"
+    new_query = auth_part if not trailing_query else f"{auth_part}&{trailing_query}"
+
+    request.scope["path"] = new_path
+    request.scope["raw_path"] = new_path.encode("utf-8")
+    request.scope["query_string"] = new_query.encode("utf-8")
+
+
+async def _best_effort(
+    name: str, awaitable, timeout_s: float = _SHUTDOWN_TIMEOUT_S
+) -> None:
+    """Run a shutdown step with timeout; never raise to callers."""
+    try:
+        await asyncio.wait_for(awaitable, timeout=timeout_s)
+    except TimeoutError:
+        logger.warning(f"Shutdown step timed out: {name} ({timeout_s}s)")
+    except Exception as e:
+        logger.warning(f"Shutdown step failed: {name}: {type(e).__name__}: {e}")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan manager."""
+    settings = get_settings()
+    logger.info("Starting Claude Code Proxy...")
+
+    # Initialize messaging platform if configured
+    messaging_platform = None
+    message_handler = None
+    cli_manager = None
+
+    try:
+        # Use the messaging factory to create the right platform
+        from messaging.platforms.factory import create_messaging_platform
+
+        messaging_platform = create_messaging_platform(
+            platform_type=settings.messaging_platform,
+            bot_token=settings.telegram_bot_token,
+            allowed_user_id=settings.allowed_telegram_user_id,
+            discord_bot_token=settings.discord_bot_token,
+            allowed_discord_channels=settings.allowed_discord_channels,
+        )
+
+        if messaging_platform:
+            from cli.manager import CLISessionManager
+            from messaging.handler import ClaudeMessageHandler
+            from messaging.session import SessionStore
+
+            # Setup workspace - CLI runs in allowed_dir if set (e.g. project root)
+            workspace = (
+                os.path.abspath(settings.allowed_dir)
+                if settings.allowed_dir
+                else os.getcwd()
+            )
+            os.makedirs(workspace, exist_ok=True)
+
+            # Session data stored in agent_workspace
+            data_path = os.path.abspath(settings.claude_workspace)
+            os.makedirs(data_path, exist_ok=True)
+
+            api_url = f"http://{settings.host}:{settings.port}/v1"
+            allowed_dirs = [workspace] if settings.allowed_dir else []
+            plans_dir_abs = os.path.abspath(
+                os.path.join(settings.claude_workspace, "plans")
+            )
+            plans_directory = os.path.relpath(plans_dir_abs, workspace)
+            cli_manager = CLISessionManager(
+                workspace_path=workspace,
+                api_url=api_url,
+                allowed_dirs=allowed_dirs,
+                plans_directory=plans_directory,
+            )
+
+            # Initialize session store
+            session_store = SessionStore(
+                storage_path=os.path.join(data_path, "sessions.json")
+            )
+
+            # Create and register message handler
+            message_handler = ClaudeMessageHandler(
+                platform=messaging_platform,
+                cli_manager=cli_manager,
+                session_store=session_store,
+            )
+
+            # Restore tree state if available
+            saved_trees = session_store.get_all_trees()
+            if saved_trees:
+                logger.info(f"Restoring {len(saved_trees)} conversation trees...")
+                from messaging.trees.queue_manager import TreeQueueManager
+
+                message_handler.replace_tree_queue(
+                    TreeQueueManager.from_dict(
+                        {
+                            "trees": saved_trees,
+                            "node_to_tree": session_store.get_node_mapping(),
+                        },
+                        queue_update_callback=message_handler.update_queue_positions,
+                        node_started_callback=message_handler.mark_node_processing,
+                    )
+                )
+                # Reconcile restored state - anything PENDING/IN_PROGRESS is lost across restart
+                if message_handler.tree_queue.cleanup_stale_nodes() > 0:
+                    # Sync back and save
+                    tree_data = message_handler.tree_queue.to_dict()
+                    session_store.sync_from_tree_data(
+                        tree_data["trees"], tree_data["node_to_tree"]
+                    )
+
+            # Wire up the handler
+            messaging_platform.on_message(message_handler.handle_message)
+
+            # Start the platform
+            await messaging_platform.start()
+            logger.info(
+                f"{messaging_platform.name} platform started with message handler"
+            )
+
+    except ImportError as e:
+        logger.warning(f"Messaging module import error: {e}")
+    except Exception as e:
+        logger.error(f"Failed to start messaging platform: {e}")
+        import traceback
+
+        logger.error(traceback.format_exc())
+
+    # Store in app state for access in routes
+    app.state.messaging_platform = messaging_platform
+    app.state.message_handler = message_handler
+    app.state.cli_manager = cli_manager
+
+    yield
+
+    # Cleanup
+    if message_handler and hasattr(message_handler, "session_store"):
+        try:
+            message_handler.session_store.flush_pending_save()
+        except Exception as e:
+            logger.warning(f"Session store flush on shutdown: {e}")
+    logger.info("Shutdown requested, cleaning up...")
+    if messaging_platform:
+        await _best_effort("messaging_platform.stop", messaging_platform.stop())
+    if cli_manager:
+        await _best_effort("cli_manager.stop_all", cli_manager.stop_all())
+    await _best_effort("cleanup_provider", cleanup_provider())
+
+    # Ensure background limiter worker doesn't keep the loop alive.
+    try:
+        from messaging.limiter import MessagingRateLimiter
+
+        await _best_effort(
+            "MessagingRateLimiter.shutdown_instance",
+            MessagingRateLimiter.shutdown_instance(),
+            timeout_s=2.0,
+        )
+    except Exception:
+        # Limiter may never have been imported/initialized.
+        pass
+
+    logger.info("Server shut down cleanly")
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application."""
+    app = FastAPI(
+        title="Claude Code Proxy",
+        version="2.0.0",
+        lifespan=lifespan,
+    )
+
+    @app.middleware("http")
+    async def enforce_api_key(request: Request, call_next):
+        """Enforce API key for every request before routing/method matching."""
+        _normalize_malformed_query_base_url_request(request)
+        try:
+            validate_request_api_key(request, get_settings())
+        except HTTPException as exc:
+            return JSONResponse(
+                status_code=exc.status_code,
+                content={"detail": exc.detail},
+            )
+        return await call_next(request)
+
+    # Register routes
+    app.include_router(router)
+
+    # Exception handlers
+    @app.exception_handler(ProviderError)
+    async def provider_error_handler(request: Request, exc: ProviderError):
+        """Handle provider-specific errors and return Anthropic format."""
+        logger.error(f"Provider Error: {exc.error_type} - {exc.message}")
+        return JSONResponse(
+            status_code=exc.status_code,
+            content=exc.to_anthropic_format(),
+        )
+
+    @app.exception_handler(Exception)
+    async def general_error_handler(request: Request, exc: Exception):
+        """Handle general errors and return Anthropic format."""
+        logger.error(f"General Error: {exc!s}")
+        import traceback
+
+        logger.error(traceback.format_exc())
+        return JSONResponse(
+            status_code=500,
+            content={
+                "type": "error",
+                "error": {
+                    "type": "api_error",
+                    "message": "An unexpected error occurred.",
+                },
+            },
+        )
+
+    return app
+
+
+# Default app instance for uvicorn
+app = create_app()

Claude_Code/api/command_utils.py

@@ -0,0 +1,139 @@
+"""Command parsing utilities for API optimizations."""
+
+import shlex
+
+
+def extract_command_prefix(command: str) -> str:
+    """Extract the command prefix for fast prefix detection.
+
+    Parses a shell command safely, handling environment variables and
+    command injection attempts. Returns the command prefix suitable
+    for quick identification.
+
+    Returns:
+        Command prefix (e.g., "git", "git commit", "npm install")
+        or "none" if no valid command found
+    """
+    if "`" in command or "$(" in command:
+        return "command_injection_detected"
+
+    try:
+        parts = shlex.split(command, posix=False)
+        if not parts:
+            return "none"
+
+        env_prefix = []
+        cmd_start = 0
+        for i, part in enumerate(parts):
+            if "=" in part and not part.startswith("-"):
+                env_prefix.append(part)
+                cmd_start = i + 1
+            else:
+                break
+
+        if cmd_start >= len(parts):
+            return "none"
+
+        cmd_parts = parts[cmd_start:]
+        if not cmd_parts:
+            return "none"
+
+        first_word = cmd_parts[0]
+        two_word_commands = {
+            "git",
+            "npm",
+            "docker",
+            "kubectl",
+            "cargo",
+            "go",
+            "pip",
+            "yarn",
+        }
+
+        if first_word in two_word_commands and len(cmd_parts) > 1:
+            second_word = cmd_parts[1]
+            if not second_word.startswith("-"):
+                return f"{first_word} {second_word}"
+            return first_word
+        return first_word if not env_prefix else " ".join(env_prefix) + " " + first_word
+
+    except ValueError:
+        return command.split()[0] if command.split() else "none"
+
+
+def extract_filepaths_from_command(command: str, output: str) -> str:
+    """Extract file paths from a command locally without API call.
+
+    Determines if the command reads file contents and extracts paths accordingly.
+    Commands like ls/dir/find just list files, so return empty.
+    Commands like cat/head/tail actually read contents, so extract the file path.
+
+    Returns:
+        Filepath extraction result in <filepaths> format
+    """
+    listing_commands = {
+        "ls",
+        "dir",
+        "find",
+        "tree",
+        "pwd",
+        "cd",
+        "mkdir",
+        "rmdir",
+        "rm",
+    }
+
+    reading_commands = {"cat", "head", "tail", "less", "more", "bat", "type"}
+
+    try:
+        parts = shlex.split(command, posix=False)
+        if not parts:
+            return "<filepaths>\n</filepaths>"
+
+        base_cmd = parts[0].split("/")[-1].split("\\")[-1].lower()
+
+        if base_cmd in listing_commands:
+            return "<filepaths>\n</filepaths>"
+
+        if base_cmd in reading_commands:
+            filepaths = []
+            for part in parts[1:]:
+                if part.startswith("-"):
+                    continue
+                filepaths.append(part)
+
+            if filepaths:
+                paths_str = "\n".join(filepaths)
+                return f"<filepaths>\n{paths_str}\n</filepaths>"
+            return "<filepaths>\n</filepaths>"
+
+        if base_cmd == "grep":
+            flags_with_args = {"-e", "-f", "-m", "-A", "-B", "-C"}
+            pattern_provided_via_flag = False
+            positional: list[str] = []
+
+            skip_next = False
+            for part in parts[1:]:
+                if skip_next:
+                    skip_next = False
+                    continue
+
+                if part.startswith("-"):
+                    if part in flags_with_args:
+                        if part in {"-e", "-f"}:
+                            pattern_provided_via_flag = True
+                        skip_next = True
+                    continue
+
+                positional.append(part)
+
+            filepaths = positional if pattern_provided_via_flag else positional[1:]
+            if filepaths:
+                paths_str = "\n".join(filepaths)
+                return f"<filepaths>\n{paths_str}\n</filepaths>"
+            return "<filepaths>\n</filepaths>"
+
+        return "<filepaths>\n</filepaths>"
+
+    except Exception:
+        return "<filepaths>\n</filepaths>"

Claude_Code/api/dependencies.py

@@ -0,0 +1,226 @@
+"""Dependency injection for FastAPI."""
+
+from urllib.parse import unquote_plus
+
+from fastapi import Depends, HTTPException, Request
+from loguru import logger
+
+from config.settings import Settings
+from config.settings import get_settings as _get_settings
+from providers.base import BaseProvider, ProviderConfig
+from providers.common import get_user_facing_error_message
+from providers.exceptions import AuthenticationError
+from providers.llamacpp import LlamaCppProvider
+from providers.lmstudio import LMStudioProvider
+from providers.nvidia_nim import NVIDIA_NIM_BASE_URL, NvidiaNimProvider
+from providers.open_router import OPENROUTER_BASE_URL, OpenRouterProvider
+
+# Provider registry: keyed by provider type string, lazily populated
+_providers: dict[str, BaseProvider] = {}
+
+
+def get_settings() -> Settings:
+    """Get application settings via dependency injection."""
+    return _get_settings()
+
+
+def _create_provider_for_type(provider_type: str, settings: Settings) -> BaseProvider:
+    """Construct and return a new provider instance for the given provider type."""
+    if provider_type == "nvidia_nim":
+        if not settings.nvidia_nim_api_key or not settings.nvidia_nim_api_key.strip():
+            raise AuthenticationError(
+                "NVIDIA_NIM_API_KEY is not set. Add it to your .env file. "
+                "Get a key at https://build.nvidia.com/settings/api-keys"
+            )
+        config = ProviderConfig(
+            api_key=settings.nvidia_nim_api_key,
+            base_url=NVIDIA_NIM_BASE_URL,
+            rate_limit=settings.provider_rate_limit,
+            rate_window=settings.provider_rate_window,
+            max_concurrency=settings.provider_max_concurrency,
+            http_read_timeout=settings.http_read_timeout,
+            http_write_timeout=settings.http_write_timeout,
+            http_connect_timeout=settings.http_connect_timeout,
+        )
+        return NvidiaNimProvider(config, nim_settings=settings.nim)
+    if provider_type == "open_router":
+        if not settings.open_router_api_key or not settings.open_router_api_key.strip():
+            raise AuthenticationError(
+                "OPENROUTER_API_KEY is not set. Add it to your .env file. "
+                "Get a key at https://openrouter.ai/keys"
+            )
+        config = ProviderConfig(
+            api_key=settings.open_router_api_key,
+            base_url=OPENROUTER_BASE_URL,
+            rate_limit=settings.provider_rate_limit,
+            rate_window=settings.provider_rate_window,
+            max_concurrency=settings.provider_max_concurrency,
+            http_read_timeout=settings.http_read_timeout,
+            http_write_timeout=settings.http_write_timeout,
+            http_connect_timeout=settings.http_connect_timeout,
+        )
+        return OpenRouterProvider(config)
+    if provider_type == "lmstudio":
+        config = ProviderConfig(
+            api_key="lm-studio",
+            base_url=settings.lm_studio_base_url,
+            rate_limit=settings.provider_rate_limit,
+            rate_window=settings.provider_rate_window,
+            max_concurrency=settings.provider_max_concurrency,
+            http_read_timeout=settings.http_read_timeout,
+            http_write_timeout=settings.http_write_timeout,
+            http_connect_timeout=settings.http_connect_timeout,
+        )
+        return LMStudioProvider(config)
+    if provider_type == "llamacpp":
+        config = ProviderConfig(
+            api_key="llamacpp",
+            base_url=settings.llamacpp_base_url,
+            rate_limit=settings.provider_rate_limit,
+            rate_window=settings.provider_rate_window,
+            max_concurrency=settings.provider_max_concurrency,
+            http_read_timeout=settings.http_read_timeout,
+            http_write_timeout=settings.http_write_timeout,
+            http_connect_timeout=settings.http_connect_timeout,
+        )
+        return LlamaCppProvider(config)
+    logger.error(
+        "Unknown provider_type: '{}'. Supported: 'nvidia_nim', 'open_router', 'lmstudio', 'llamacpp'",
+        provider_type,
+    )
+    raise ValueError(
+        f"Unknown provider_type: '{provider_type}'. "
+        f"Supported: 'nvidia_nim', 'open_router', 'lmstudio', 'llamacpp'"
+    )
+
+
+def get_provider_for_type(provider_type: str) -> BaseProvider:
+    """Get or create a provider for the given provider type.
+
+    Providers are cached in the registry and reused across requests.
+    """
+    if provider_type not in _providers:
+        try:
+            _providers[provider_type] = _create_provider_for_type(
+                provider_type, get_settings()
+            )
+        except AuthenticationError as e:
+            raise HTTPException(
+                status_code=503, detail=get_user_facing_error_message(e)
+            ) from e
+        logger.info("Provider initialized: {}", provider_type)
+    return _providers[provider_type]
+
+
+def validate_request_api_key(request: Request, settings: Settings) -> None:
+    """Validate a request against configured server API key.
+
+    Checks `x-api-key` header, `Authorization: Bearer ...`, or query parameter `psw`
+    against `Settings.anthropic_auth_token`. If `ANTHROPIC_AUTH_TOKEN` is empty, this is a no-op.
+
+    Supports Hugging Face Spaces private deployments via query parameter authentication:
+    - Append `?psw=your-token` to the base URL
+    - Or `?psw:your-token` (URL-encoded colon becomes %3A)
+    """
+    anthropic_auth_token = settings.anthropic_auth_token
+    if not anthropic_auth_token:
+        # No API key configured -> allow
+        return
+
+    # Allow Hugging Face private Space signed browser requests for UI pages.
+    # This keeps API routes protected while avoiding 401 on Space shell probes.
+    if _is_hf_signed_page_request(request):
+        return
+
+    token = None
+
+    # Check headers first (preferred)
+    header = (
+        request.headers.get("x-api-key")
+        or request.headers.get("authorization")
+        or request.headers.get("anthropic-auth-token")
+    )
+    if header:
+        # Support both raw key in X-API-Key and Bearer token in Authorization
+        token = header
+        if header.lower().startswith("bearer "):
+            token = header.split(" ", 1)[1]
+        # Strip anything after the first colon to handle tokens with appended model names
+        if token and ":" in token:
+            token = token.split(":", 1)[0]
+    else:
+        token = _extract_query_token(request)
+
+    if not token:
+        raise HTTPException(status_code=401, detail="Missing API key")
+
+    if token != anthropic_auth_token:
+        raise HTTPException(status_code=401, detail="Invalid API key")
+
+
+def _extract_query_token(request: Request) -> str | None:
+    """Extract auth token from query string for private proxy deployments."""
+    query_params = request.query_params
+    if "psw" in query_params:
+        token = query_params["psw"]
+        if token and ":" in token:
+            return token.split(":", 1)[0]
+        return token or None
+
+    raw_query_bytes = request.scope.get("query_string", b"")
+    raw_query = raw_query_bytes.decode("utf-8", errors="ignore")
+    if not raw_query:
+        return None
+
+    for part in raw_query.split("&"):
+        if part.startswith("psw:"):
+            token = unquote_plus(part[len("psw:") :])
+            if token and ":" in token:
+                return token.split(":", 1)[0]
+            return token or None
+        if part.startswith("psw%3A") or part.startswith("psw%3a"):
+            token = unquote_plus(part[len("psw%3A") :])
+            if token and ":" in token:
+                return token.split(":", 1)[0]
+            return token or None
+
+    return None
+
+
+def _is_hf_signed_page_request(request: Request) -> bool:
+    """Return True for Hugging Face signed browser requests to non-API pages."""
+    if request.method not in {"GET", "HEAD"}:
+        return False
+
+    if request.url.path.startswith("/v1/"):
+        return False
+
+    if "__sign" not in request.query_params:
+        return False
+
+    accept = request.headers.get("accept", "").lower()
+    return "text/html" in accept or "*/*" in accept
+
+
+def require_api_key(
+    request: Request, settings: Settings = Depends(get_settings)
+) -> None:
+    """FastAPI dependency wrapper for API key validation."""
+    validate_request_api_key(request, settings)
+
+
+def get_provider() -> BaseProvider:
+    """Get or create the default provider (based on MODEL env var).
+
+    Backward-compatible convenience for health/root endpoints and tests.
+    """
+    return get_provider_for_type(get_settings().provider_type)
+
+
+async def cleanup_provider():
+    """Cleanup all provider resources."""
+    global _providers
+    for provider in _providers.values():
+        await provider.cleanup()
+    _providers = {}
+    logger.debug("Provider cleanup completed")

Claude_Code/api/detection.py

@@ -0,0 +1,130 @@
+"""Request detection utilities for API optimizations.
+
+Detects quota checks, title generation, prefix detection, suggestion mode,
+and filepath extraction requests to enable fast-path responses.
+"""
+
+from providers.common.text import extract_text_from_content
+
+from .models.anthropic import MessagesRequest
+
+
+def is_quota_check_request(request_data: MessagesRequest) -> bool:
+    """Check if this is a quota probe request.
+
+    Quota checks are typically simple requests with max_tokens=1
+    and a single message containing the word "quota".
+    """
+    if (
+        request_data.max_tokens == 1
+        and len(request_data.messages) == 1
+        and request_data.messages[0].role == "user"
+    ):
+        text = extract_text_from_content(request_data.messages[0].content)
+        if "quota" in text.lower():
+            return True
+    return False
+
+
+def is_title_generation_request(request_data: MessagesRequest) -> bool:
+    """Check if this is a conversation title generation request.
+
+    Title generation requests are detected by a system prompt containing
+    title extraction instructions, no tools, and a single user message.
+    """
+    if not request_data.system or request_data.tools:
+        return False
+    system_text = extract_text_from_content(request_data.system).lower()
+    return "new conversation topic" in system_text and "title" in system_text
+
+
+def is_prefix_detection_request(request_data: MessagesRequest) -> tuple[bool, str]:
+    """Check if this is a fast prefix detection request.
+
+    Prefix detection requests contain a policy_spec block and
+    a Command: section for extracting shell command prefixes.
+
+    Returns:
+        Tuple of (is_prefix_request, command_string)
+    """
+    if len(request_data.messages) != 1 or request_data.messages[0].role != "user":
+        return False, ""
+
+    content = extract_text_from_content(request_data.messages[0].content)
+
+    if "<policy_spec>" in content and "Command:" in content:
+        try:
+            cmd_start = content.rfind("Command:") + len("Command:")
+            return True, content[cmd_start:].strip()
+        except Exception:
+            pass
+
+    return False, ""
+
+
+def is_suggestion_mode_request(request_data: MessagesRequest) -> bool:
+    """Check if this is a suggestion mode request.
+
+    Suggestion mode requests contain "[SUGGESTION MODE:" in the user's message,
+    used for auto-suggesting what the user might type next.
+    """
+    for msg in request_data.messages:
+        if msg.role == "user":
+            text = extract_text_from_content(msg.content)
+            if "[SUGGESTION MODE:" in text:
+                return True
+    return False
+
+
+def is_filepath_extraction_request(
+    request_data: MessagesRequest,
+) -> tuple[bool, str, str]:
+    """Check if this is a filepath extraction request.
+
+    Filepath extraction requests have a single user message with
+    "Command:" and "Output:" sections, asking to extract file paths
+    from command output.
+
+    Returns:
+        Tuple of (is_filepath_request, command, output)
+    """
+    if len(request_data.messages) != 1 or request_data.messages[0].role != "user":
+        return False, "", ""
+    if request_data.tools:
+        return False, "", ""
+
+    content = extract_text_from_content(request_data.messages[0].content)
+
+    if "Command:" not in content or "Output:" not in content:
+        return False, "", ""
+
+    # Match if user content OR system block indicates filepath extraction
+    user_has_filepaths = (
+        "filepaths" in content.lower() or "<filepaths>" in content.lower()
+    )
+    system_text = (
+        extract_text_from_content(request_data.system) if request_data.system else ""
+    )
+    system_has_extract = (
+        "extract any file paths" in system_text.lower()
+        or "file paths that this command" in system_text.lower()
+    )
+    if not user_has_filepaths and not system_has_extract:
+        return False, "", ""
+
+    try:
+        cmd_start = content.find("Command:") + len("Command:")
+        output_marker = content.find("Output:", cmd_start)
+        if output_marker == -1:
+            return False, "", ""
+
+        command = content[cmd_start:output_marker].strip()
+        output = content[output_marker + len("Output:") :].strip()
+
+        for marker in ["<", "\n\n"]:
+            if marker in output:
+                output = output.split(marker)[0].strip()
+
+        return True, command, output
+    except Exception:
+        return False, "", ""

Claude_Code/api/models/__init__.py

@@ -0,0 +1,35 @@
+"""API models exports."""
+
+from .anthropic import (
+    ContentBlockImage,
+    ContentBlockText,
+    ContentBlockThinking,
+    ContentBlockToolResult,
+    ContentBlockToolUse,
+    Message,
+    MessagesRequest,
+    Role,
+    SystemContent,
+    ThinkingConfig,
+    TokenCountRequest,
+    Tool,
+)
+from .responses import MessagesResponse, TokenCountResponse, Usage
+
+__all__ = [
+    "ContentBlockImage",
+    "ContentBlockText",
+    "ContentBlockThinking",
+    "ContentBlockToolResult",
+    "ContentBlockToolUse",
+    "Message",
+    "MessagesRequest",
+    "MessagesResponse",
+    "Role",
+    "SystemContent",
+    "ThinkingConfig",
+    "TokenCountRequest",
+    "TokenCountResponse",
+    "Tool",
+    "Usage",
+]

Claude_Code/api/models/anthropic.py

@@ -0,0 +1,134 @@
+"""Pydantic models for Anthropic-compatible requests."""
+
+from enum import StrEnum
+from typing import Any, Literal
+
+from loguru import logger
+from pydantic import BaseModel, field_validator, model_validator
+
+from config.settings import Settings, get_settings
+
+
+# =============================================================================
+# Content Block Types
+# =============================================================================
+class Role(StrEnum):
+    user = "user"
+    assistant = "assistant"
+    system = "system"
+
+
+class ContentBlockText(BaseModel):
+    type: Literal["text"]
+    text: str
+
+
+class ContentBlockImage(BaseModel):
+    type: Literal["image"]
+    source: dict[str, Any]
+
+
+class ContentBlockToolUse(BaseModel):
+    type: Literal["tool_use"]
+    id: str
+    name: str
+    input: dict[str, Any]
+
+
+class ContentBlockToolResult(BaseModel):
+    type: Literal["tool_result"]
+    tool_use_id: str
+    content: str | list[Any] | dict[str, Any]
+
+
+class ContentBlockThinking(BaseModel):
+    type: Literal["thinking"]
+    thinking: str
+
+
+class SystemContent(BaseModel):
+    type: Literal["text"]
+    text: str
+
+
+# =============================================================================
+# Message Types
+# =============================================================================
+class Message(BaseModel):
+    role: Literal["user", "assistant"]
+    content: (
+        str
+        | list[
+            ContentBlockText
+            | ContentBlockImage
+            | ContentBlockToolUse
+            | ContentBlockToolResult
+            | ContentBlockThinking
+        ]
+    )
+    reasoning_content: str | None = None
+
+
+class Tool(BaseModel):
+    name: str
+    description: str | None = None
+    input_schema: dict[str, Any]
+
+
+class ThinkingConfig(BaseModel):
+    enabled: bool = True
+
+
+# =============================================================================
+# Request Models
+# =============================================================================
+class MessagesRequest(BaseModel):
+    model: str
+    max_tokens: int | None = None
+    messages: list[Message]
+    system: str | list[SystemContent] | None = None
+    stop_sequences: list[str] | None = None
+    stream: bool | None = True
+    temperature: float | None = None
+    top_p: float | None = None
+    top_k: int | None = None
+    metadata: dict[str, Any] | None = None
+    tools: list[Tool] | None = None
+    tool_choice: dict[str, Any] | None = None
+    thinking: ThinkingConfig | None = None
+    extra_body: dict[str, Any] | None = None
+    original_model: str | None = None
+    resolved_provider_model: str | None = None
+
+    @model_validator(mode="after")
+    def map_model(self) -> "MessagesRequest":
+        """Map any Claude model name to the configured model (model-aware)."""
+        settings = get_settings()
+        if self.original_model is None:
+            self.original_model = self.model
+
+        resolved_full = settings.resolve_model(self.original_model)
+        self.resolved_provider_model = resolved_full
+        self.model = Settings.parse_model_name(resolved_full)
+
+        if self.model != self.original_model:
+            logger.debug(f"MODEL MAPPING: '{self.original_model}' -> '{self.model}'")
+
+        return self
+
+
+class TokenCountRequest(BaseModel):
+    model: str
+    messages: list[Message]
+    system: str | list[SystemContent] | None = None
+    tools: list[Tool] | None = None
+    thinking: ThinkingConfig | None = None
+    tool_choice: dict[str, Any] | None = None
+
+    @field_validator("model")
+    @classmethod
+    def validate_model_field(cls, v: str, info) -> str:
+        """Map any Claude model name to the configured model (model-aware)."""
+        settings = get_settings()
+        resolved_full = settings.resolve_model(v)
+        return Settings.parse_model_name(resolved_full)

Claude_Code/api/models/responses.py

@@ -0,0 +1,33 @@
+"""Pydantic models for API responses."""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+from .anthropic import ContentBlockText, ContentBlockThinking, ContentBlockToolUse
+
+
+class TokenCountResponse(BaseModel):
+    input_tokens: int
+
+
+class Usage(BaseModel):
+    input_tokens: int
+    output_tokens: int
+    cache_creation_input_tokens: int = 0
+    cache_read_input_tokens: int = 0
+
+
+class MessagesResponse(BaseModel):
+    id: str
+    model: str
+    role: Literal["assistant"] = "assistant"
+    content: list[
+        ContentBlockText | ContentBlockToolUse | ContentBlockThinking | dict[str, Any]
+    ]
+    type: Literal["message"] = "message"
+    stop_reason: (
+        Literal["end_turn", "max_tokens", "stop_sequence", "tool_use"] | None
+    ) = None
+    stop_sequence: str | None = None
+    usage: Usage

Claude_Code/api/optimization_handlers.py

@@ -0,0 +1,147 @@
+"""Optimization handlers for fast-path API responses.
+
+Each handler returns a MessagesResponse if the request matches and the
+optimization is enabled, otherwise None.
+"""
+
+import uuid
+
+from loguru import logger
+
+from config.settings import Settings
+
+from .command_utils import extract_command_prefix, extract_filepaths_from_command
+from .detection import (
+    is_filepath_extraction_request,
+    is_prefix_detection_request,
+    is_quota_check_request,
+    is_suggestion_mode_request,
+    is_title_generation_request,
+)
+from .models.anthropic import MessagesRequest
+from .models.responses import MessagesResponse, Usage
+
+
+def try_prefix_detection(
+    request_data: MessagesRequest, settings: Settings
+) -> MessagesResponse | None:
+    """Fast prefix detection - return command prefix without API call."""
+    if not settings.fast_prefix_detection:
+        return None
+
+    is_prefix_req, command = is_prefix_detection_request(request_data)
+    if not is_prefix_req:
+        return None
+
+    logger.info("Optimization: Fast prefix detection request")
+    return MessagesResponse(
+        id=f"msg_{uuid.uuid4()}",
+        model=request_data.model,
+        content=[{"type": "text", "text": extract_command_prefix(command)}],
+        stop_reason="end_turn",
+        usage=Usage(input_tokens=100, output_tokens=5),
+    )
+
+
+def try_quota_mock(
+    request_data: MessagesRequest, settings: Settings
+) -> MessagesResponse | None:
+    """Mock quota probe requests."""
+    if not settings.enable_network_probe_mock:
+        return None
+    if not is_quota_check_request(request_data):
+        return None
+
+    logger.info("Optimization: Intercepted and mocked quota probe")
+    return MessagesResponse(
+        id=f"msg_{uuid.uuid4()}",
+        model=request_data.model,
+        role="assistant",
+        content=[{"type": "text", "text": "Quota check passed."}],
+        stop_reason="end_turn",
+        usage=Usage(input_tokens=10, output_tokens=5),
+    )
+
+
+def try_title_skip(
+    request_data: MessagesRequest, settings: Settings
+) -> MessagesResponse | None:
+    """Skip title generation requests."""
+    if not settings.enable_title_generation_skip:
+        return None
+    if not is_title_generation_request(request_data):
+        return None
+
+    logger.info("Optimization: Skipped title generation request")
+    return MessagesResponse(
+        id=f"msg_{uuid.uuid4()}",
+        model=request_data.model,
+        role="assistant",
+        content=[{"type": "text", "text": "Conversation"}],
+        stop_reason="end_turn",
+        usage=Usage(input_tokens=100, output_tokens=5),
+    )
+
+
+def try_suggestion_skip(
+    request_data: MessagesRequest, settings: Settings
+) -> MessagesResponse | None:
+    """Skip suggestion mode requests."""
+    if not settings.enable_suggestion_mode_skip:
+        return None
+    if not is_suggestion_mode_request(request_data):
+        return None
+
+    logger.info("Optimization: Skipped suggestion mode request")
+    return MessagesResponse(
+        id=f"msg_{uuid.uuid4()}",
+        model=request_data.model,
+        role="assistant",
+        content=[{"type": "text", "text": ""}],
+        stop_reason="end_turn",
+        usage=Usage(input_tokens=100, output_tokens=1),
+    )
+
+
+def try_filepath_mock(
+    request_data: MessagesRequest, settings: Settings
+) -> MessagesResponse | None:
+    """Mock filepath extraction requests."""
+    if not settings.enable_filepath_extraction_mock:
+        return None
+
+    is_fp, cmd, output = is_filepath_extraction_request(request_data)
+    if not is_fp:
+        return None
+
+    filepaths = extract_filepaths_from_command(cmd, output)
+    logger.info("Optimization: Mocked filepath extraction")
+    return MessagesResponse(
+        id=f"msg_{uuid.uuid4()}",
+        model=request_data.model,
+        role="assistant",
+        content=[{"type": "text", "text": filepaths}],
+        stop_reason="end_turn",
+        usage=Usage(input_tokens=100, output_tokens=10),
+    )
+
+
+# Cheapest/most common optimizations first for faster short-circuit.
+OPTIMIZATION_HANDLERS = [
+    try_quota_mock,
+    try_prefix_detection,
+    try_title_skip,
+    try_suggestion_skip,
+    try_filepath_mock,
+]
+
+
+def try_optimizations(
+    request_data: MessagesRequest, settings: Settings
+) -> MessagesResponse | None:
+    """Run optimization handlers in order. Returns first match or None."""
+    for handler in OPTIMIZATION_HANDLERS:
+        result = handler(request_data, settings)
+        if result is not None:
+            return result
+    return None

Claude_Code/api/request_utils.py

@@ -0,0 +1,101 @@
+"""Request utility functions for API route handlers.
+
+Contains token counting for API requests.
+"""
+
+import json
+
+import tiktoken
+from loguru import logger
+
+from providers.common import get_block_attr
+
+ENCODER = tiktoken.get_encoding("cl100k_base")
+
+__all__ = ["get_token_count"]
+
+
+def get_token_count(
+    messages: list,
+    system: str | list | None = None,
+    tools: list | None = None,
+) -> int:
+    """Estimate token count for a request.
+
+    Uses tiktoken cl100k_base encoding to estimate token usage.
+    Includes system prompt, messages, tools, and per-message overhead.
+    """
+    total_tokens = 0
+
+    if system:
+        if isinstance(system, str):
+            total_tokens += len(ENCODER.encode(system))
+        elif isinstance(system, list):
+            for block in system:
+                text = get_block_attr(block, "text", "")
+                if text:
+                    total_tokens += len(ENCODER.encode(str(text)))
+        total_tokens += 4  # System block formatting overhead
+
+    for msg in messages:
+        if isinstance(msg.content, str):
+            total_tokens += len(ENCODER.encode(msg.content))
+        elif isinstance(msg.content, list):
+            for block in msg.content:
+                b_type = get_block_attr(block, "type") or None
+
+                if b_type == "text":
+                    text = get_block_attr(block, "text", "")
+                    total_tokens += len(ENCODER.encode(str(text)))
+                elif b_type == "thinking":
+                    thinking = get_block_attr(block, "thinking", "")
+                    total_tokens += len(ENCODER.encode(str(thinking)))
+                elif b_type == "tool_use":
+                    name = get_block_attr(block, "name", "")
+                    inp = get_block_attr(block, "input", {})
+                    block_id = get_block_attr(block, "id", "")
+                    total_tokens += len(ENCODER.encode(str(name)))
+                    total_tokens += len(ENCODER.encode(json.dumps(inp)))
+                    total_tokens += len(ENCODER.encode(str(block_id)))
+                    total_tokens += 15
+                elif b_type == "image":
+                    source = get_block_attr(block, "source")
+                    if isinstance(source, dict):
+                        data = source.get("data") or source.get("base64") or ""
+                        if data:
+                            total_tokens += max(85, len(data) // 3000)
+                        else:
+                            total_tokens += 765
+                    else:
+                        total_tokens += 765
+                elif b_type == "tool_result":
+                    content = get_block_attr(block, "content", "")
+                    tool_use_id = get_block_attr(block, "tool_use_id", "")
+                    if isinstance(content, str):
+                        total_tokens += len(ENCODER.encode(content))
+                    else:
+                        total_tokens += len(ENCODER.encode(json.dumps(content)))
+                    total_tokens += len(ENCODER.encode(str(tool_use_id)))
+                    total_tokens += 8
+                else:
+                    logger.debug(
+                        "Unexpected block type %r, falling back to json/str encoding",
+                        b_type,
+                    )
+                    try:
+                        total_tokens += len(ENCODER.encode(json.dumps(block)))
+                    except TypeError, ValueError:
+                        total_tokens += len(ENCODER.encode(str(block)))
+
+    if tools:
+        for tool in tools:
+            tool_str = (
+                tool.name + (tool.description or "") + json.dumps(tool.input_schema)
+            )
+            total_tokens += len(ENCODER.encode(tool_str))
+
+    total_tokens += len(messages) * 4
+    if tools:
+        total_tokens += len(tools) * 5
+
+    return max(1, total_tokens)

Claude_Code/api/routes.py

@@ -0,0 +1,345 @@
+"""FastAPI route handlers."""
+
+import os
+import shutil
+import tempfile
+import time
+import traceback
+import uuid
+from pathlib import Path
+
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Request
+from fastapi.responses import HTMLResponse, StreamingResponse
+from loguru import logger
+
+from config.settings import Settings
+from providers.common import get_user_facing_error_message
+from providers.exceptions import InvalidRequestError, ProviderError
+
+from .dependencies import get_provider_for_type, get_settings, require_api_key
+from .models.anthropic import MessagesRequest, TokenCountRequest
+from .models.responses import TokenCountResponse
+from .optimization_handlers import try_optimizations
+from .request_utils import get_token_count
+
+router = APIRouter()
+
+
+def _home_page_html(status_payload: dict[str, str]) -> str:
+        """Render the home page HTML with the factory reset button."""
+        return f"""
+<!doctype html>
+<html lang=\"en\">
+<head>
+    <meta charset=\"utf-8\" />
+    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />
+    <title>Claude Code Proxy</title>
+    <style>
+        :root {{ color-scheme: dark; }}
+        body {{ margin: 0; min-height: 100vh; display: grid; place-items: center; font-family: Inter, Segoe UI, Arial, sans-serif; background: radial-gradient(1200px 600px at 20% 10%, #2e1b4a, #12131f 45%, #0b0c12); color: #e8ecff; }}
+        .card {{ width: min(92vw, 560px); background: rgba(255, 255, 255, 0.06); border: 1px solid rgba(255, 255, 255, 0.14); border-radius: 20px; padding: 28px; box-shadow: 0 20px 50px rgba(0, 0, 0, 0.35); }}
+        h1 {{ margin: 0 0 10px; font-size: 1.35rem; }}
+        p {{ margin: 0 0 8px; color: #cfd7ff; line-height: 1.45; }}
+        .meta {{ margin: 14px 0 18px; font-size: 0.95rem; color: #dfe6ff; }}
+        .meta span {{ display: inline-block; margin-right: 12px; opacity: 0.95; }}
+        button {{ border: none; border-radius: 14px; padding: 12px 18px; font-size: 1rem; font-weight: 700; color: white; cursor: pointer; background: linear-gradient(135deg, #ff507a, #7f5bff); box-shadow: 0 10px 20px rgba(127, 91, 255, 0.35); }}
+        button:disabled {{ opacity: 0.65; cursor: wait; }}
+        .status {{ margin-top: 14px; min-height: 24px; font-size: 0.95rem; color: #b8ffd8; }}
+    </style>
+</head>
+<body>
+    <div class=\"card\">
+        <h1>Claude Code Proxy</h1>
+        <p>Server is running.</p>
+        <div class=\"meta\">
+            <span><strong>Status:</strong> {status_payload['status']}</span>
+            <span><strong>Provider:</strong> {status_payload['provider']}</span>
+            <span><strong>Model:</strong> {status_payload['model']}</span>
+        </div>
+        <button id=\"resetBtn\">Factory Restart</button>
+        <div class=\"status\" id=\"status\"></div>
+    </div>
+    <script>
+        const btn = document.getElementById('resetBtn');
+        const status = document.getElementById('status');
+        btn.addEventListener('click', async () => {{
+            btn.disabled = true;
+            status.textContent = 'Resetting cache/workspace and restarting...';
+            try {{
+                const response = await fetch('/admin/factory-reset' + window.location.search, {{ method: 'POST' }});
+                const data = await response.json();
+                if (!response.ok) {{
+                    throw new Error(data.detail || 'Request failed');
+                }}
+                status.textContent = 'Restart initiated. This page will disconnect briefly.';
+            }} catch (err) {{
+                status.textContent = 'Failed: ' + (err.message || String(err));
+                btn.disabled = false;
+            }}
+        }});
+    </script>
+</body>
+</html>
+"""
+
+
+def _clear_path(path: Path) -> int:
+    """Best-effort removal of a file/directory path. Returns removed item count."""
+    if not path.exists():
+        return 0
+    try:
+        if path.is_dir():
+            shutil.rmtree(path)
+        else:
+            path.unlink()
+        return 1
+    except Exception as e:
+        logger.warning("Failed to remove path {}: {}", path, e)
+        return 0
+
+
+def _clear_workspace_contents(workspace: Path) -> int:
+    """Best-effort clear of workspace contents while preserving root directory."""
+    if not workspace.exists() or not workspace.is_dir():
+        return 0
+    removed = 0
+    for child in workspace.iterdir():
+        removed += _clear_path(child)
+    return removed
+
+
+def _clear_runtime_state(settings: Settings) -> dict[str, int]:
+    """Clear runtime caches/workspace data for a lightweight factory reset."""
+    removed = {
+        "workspace_items": 0,
+        "cache_dirs": 0,
+        "pycache_dirs": 0,
+    }
+
+    workspace = Path(settings.claude_workspace).expanduser().resolve()
+    removed["workspace_items"] = _clear_workspace_contents(workspace)
+
+    cache_dirs = [
+        Path.home() / ".cache" / "huggingface",
+        Path.home() / ".cache" / "uv",
+        Path.home() / ".cache" / "pip",
+        Path(tempfile.gettempdir()) / "huggingface",
+    ]
+    for cache_dir in cache_dirs:
+        removed["cache_dirs"] += _clear_path(cache_dir)
+
+    project_root = Path.cwd()
+    for pycache_dir in project_root.rglob("__pycache__"):
+        if ".venv" in pycache_dir.parts:
+            continue
+        removed["pycache_dirs"] += _clear_path(pycache_dir)
+
+    return removed
+
+
+def _restart_process() -> None:
+    """Terminate process so container orchestrator restarts the app."""
+    logger.warning("Factory reset requested: restarting process")
+    time.sleep(1.0)
+    os._exit(0)
+
+
+# =============================================================================
+# Routes
+# =============================================================================
+@router.post("/v1/messages")
+async def create_message(
+    request_data: MessagesRequest,
+    raw_request: Request,
+    settings: Settings = Depends(get_settings),
+    _auth=Depends(require_api_key),
+):
+    """Create a message (always streaming)."""
+
+    try:
+        if not request_data.messages:
+            raise InvalidRequestError("messages cannot be empty")
+
+        optimized = try_optimizations(request_data, settings)
+        if optimized is not None:
+            return optimized
+        logger.debug("No optimization matched, routing to provider")
+
+        # Resolve provider from the model-aware mapping
+        provider_type = Settings.parse_provider_type(
+            request_data.resolved_provider_model or settings.model
+        )
+        provider = get_provider_for_type(provider_type)
+
+        request_id = f"req_{uuid.uuid4().hex[:12]}"
+        logger.info(
+            "API_REQUEST: request_id={} model={} messages={}",
+            request_id,
+            request_data.model,
+            len(request_data.messages),
+        )
+        logger.debug("FULL_PAYLOAD [{}]: {}", request_id, request_data.model_dump())
+
+        input_tokens = get_token_count(
+            request_data.messages, request_data.system, request_data.tools
+        )
+        return StreamingResponse(
+            provider.stream_response(
+                request_data,
+                input_tokens=input_tokens,
+                request_id=request_id,
+            ),
+            media_type="text/event-stream",
+            headers={
+                "X-Accel-Buffering": "no",
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+            },
+        )
+
+    except ProviderError:
+        raise
+    except Exception as e:
+        logger.error(f"Error: {e!s}\n{traceback.format_exc()}")
+        raise HTTPException(
+            status_code=getattr(e, "status_code", 500),
+            detail=get_user_facing_error_message(e),
+        ) from e
+
+
+@router.post("/v1/messages/count_tokens")
+async def count_tokens(request_data: TokenCountRequest, _auth=Depends(require_api_key)):
+    """Count tokens for a request."""
+    request_id = f"req_{uuid.uuid4().hex[:12]}"
+    with logger.contextualize(request_id=request_id):
+        try:
+            tokens = get_token_count(
+                request_data.messages, request_data.system, request_data.tools
+            )
+            logger.info(
+                "COUNT_TOKENS: request_id={} model={} messages={} input_tokens={}",
+                request_id,
+                getattr(request_data, "model", "unknown"),
+                len(request_data.messages),
+                tokens,
+            )
+            return TokenCountResponse(input_tokens=tokens)
+        except Exception as e:
+            logger.error(
+                "COUNT_TOKENS_ERROR: request_id={} error={}\n{}",
+                request_id,
+                get_user_facing_error_message(e),
+                traceback.format_exc(),
+            )
+            raise HTTPException(
+                status_code=500, detail=get_user_facing_error_message(e)
+            ) from e
+
+
+@router.get("/")
+async def root(
+    request: Request,
+    settings: Settings = Depends(get_settings),
+    _auth=Depends(require_api_key),
+):
+    """Root endpoint (JSON for API clients, HTML for browsers)."""
+    payload = {
+        "status": "ok",
+        "provider": settings.provider_type,
+        "model": settings.model,
+    }
+    accept = request.headers.get("accept", "")
+    if "__sign" in request.query_params or "text/html" in accept.lower():
+        return HTMLResponse(content=_home_page_html(payload))
+    return payload
+
+
+@router.get("/health")
+async def health():
+    """Health check endpoint."""
+    return {"status": "healthy"}
+
+
+@router.post("/stop")
+async def stop_cli(request: Request, _auth=Depends(require_api_key)):
+    """Stop all CLI sessions and pending tasks."""
+    handler = getattr(request.app.state, "message_handler", None)
+    if not handler:
+        # Fallback if messaging not initialized
+        cli_manager = getattr(request.app.state, "cli_manager", None)
+        if cli_manager:
+            await cli_manager.stop_all()
+            logger.info("STOP_CLI: source=cli_manager cancelled_count=N/A")
+            return {"status": "stopped", "source": "cli_manager"}
+        raise HTTPException(status_code=503, detail="Messaging system not initialized")
+
+    count = await handler.stop_all_tasks()
+    logger.info("STOP_CLI: source=handler cancelled_count={}", count)
+    return {"status": "stopped", "cancelled_count": count}
+
+
+@router.get("/admin/factory-reset", response_class=HTMLResponse)
+async def factory_reset_page(request: Request, _auth=Depends(require_api_key)):
+        """Simple admin UI for one-click factory reset and restart."""
+        return """
+<!doctype html>
+<html lang=\"en\">
+<head>
+    <meta charset=\"utf-8\" />
+    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />
+    <title>Factory Reset</title>
+    <style>
+        :root { color-scheme: dark; }
+        body { margin: 0; min-height: 100vh; display: grid; place-items: center; font-family: Inter, Segoe UI, Arial, sans-serif; background: radial-gradient(1200px 600px at 20% 10%, #2e1b4a, #12131f 45%, #0b0c12); color: #e8ecff; }
+        .card { width: min(92vw, 520px); background: rgba(255, 255, 255, 0.06); border: 1px solid rgba(255, 255, 255, 0.14); border-radius: 20px; padding: 28px; box-shadow: 0 20px 50px rgba(0, 0, 0, 0.35); }
+        h1 { margin: 0 0 10px; font-size: 1.35rem; }
+        p { margin: 0 0 18px; color: #cfd7ff; line-height: 1.45; }
+        button { border: none; border-radius: 14px; padding: 12px 18px; font-size: 1rem; font-weight: 700; color: white; cursor: pointer; background: linear-gradient(135deg, #ff507a, #7f5bff); box-shadow: 0 10px 20px rgba(127, 91, 255, 0.35); }
+        button:disabled { opacity: 0.65; cursor: wait; }
+        .status { margin-top: 14px; min-height: 24px; font-size: 0.95rem; color: #b8ffd8; }
+    </style>
+</head>
+<body>
+    <div class=\"card\">
+        <h1>Factory Reset & Restart</h1>
+        <p>Clears runtime cache and workspace data, then restarts this server.</p>
+        <button id=\"resetBtn\">Factory Restart</button>
+        <div class=\"status\" id=\"status\"></div>
+    </div>
+    <script>
+        const btn = document.getElementById('resetBtn');
+        const status = document.getElementById('status');
+        btn.addEventListener('click', async () => {
+            btn.disabled = true;
+            status.textContent = 'Resetting cache/workspace and restarting...';
+            try {
+                const response = await fetch('/admin/factory-reset' + window.location.search, { method: 'POST' });
+                const data = await response.json();
+                if (!response.ok) {
+                    throw new Error(data.detail || 'Request failed');
+                }
+                status.textContent = 'Restart initiated. This page will disconnect briefly.';
+            } catch (err) {
+                status.textContent = 'Failed: ' + (err.message || String(err));
+                btn.disabled = false;
+            }
+        });
+    </script>
+</body>
+</html>
+"""
+
+
+@router.post("/admin/factory-reset")
+async def factory_reset(
+        background_tasks: BackgroundTasks,
+        settings: Settings = Depends(get_settings),
+        _auth=Depends(require_api_key),
+):
+        """Clear runtime state and restart process (for Space maintenance)."""
+        cleared = _clear_runtime_state(settings)
+        background_tasks.add_task(_restart_process)
+        return {
+                "status": "restarting",
+                "cleared": cleared,
+        }

Claude_Code/claude-pick

@@ -0,0 +1,183 @@
+#!/usr/bin/env bash
+# claude-pick — Interactive model picker for free-claude-code
+# Usage: claude-pick [extra claude args...]
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+MODELS_FILE="$SCRIPT_DIR/nvidia_nim_models.json"
+ENV_FILE="${CLAUDE_PICK_ENV_FILE:-$SCRIPT_DIR/.env}"
+PORT="${CLAUDE_PICK_PORT:-8082}"
+BASE_URL="http://localhost:$PORT"
+OPENROUTER_MODELS_URL="https://openrouter.ai/api/v1/models"
+DEFAULT_LM_STUDIO_BASE_URL="http://localhost:1234/v1"
+DEFAULT_LLAMACPP_BASE_URL="http://localhost:8080/v1"
+
+if ! command -v python3 >/dev/null 2>&1; then
+    echo "Error: python3 is required." >&2
+    exit 1
+fi
+
+read_env_value() {
+    local key="$1"
+    [[ -f "$ENV_FILE" ]] || return 0
+
+    local raw
+    raw="$(grep -E "^[[:space:]]*${key}[[:space:]]*=" "$ENV_FILE" | tail -n 1 || true)"
+    raw="${raw#*=}"
+    raw="${raw%%#*}"
+    raw="$(echo "$raw" | xargs || true)"
+    raw="${raw%\"}"
+    raw="${raw#\"}"
+    raw="${raw%\'}"
+    raw="${raw#\'}"
+    echo "$raw"
+}
+
+if ! command -v fzf >/dev/null 2>&1; then
+    echo "Error: fzf is required for the model picker." >&2
+    echo "Install it from: https://github.com/junegunn/fzf" >&2
+    exit 1
+fi
+
+parse_models_from_json() {
+    python3 -c '
+import json, sys
+try:
+    payload = json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+for item in payload.get("data", []):
+    model_id = item.get("id")
+    if model_id:
+        print(model_id)
+'
+}
+
+get_nvidia_models() {
+    if [[ ! -f "$MODELS_FILE" ]]; then
+        echo "Error: $MODELS_FILE not found." >&2
+        echo "Run: curl \"https://integrate.api.nvidia.com/v1/models\" > nvidia_nim_models.json" >&2
+        exit 1
+    fi
+
+    python3 -c '
+import json, sys
+with open(sys.argv[1], "r", encoding="utf-8") as f:
+    payload = json.load(f)
+for item in payload.get("data", []):
+    model_id = item.get("id")
+    if model_id:
+        print(model_id)
+' "$MODELS_FILE"
+}
+
+get_openrouter_models() {
+    if ! command -v curl >/dev/null 2>&1; then
+        echo "Error: curl is required for OpenRouter model discovery." >&2
+        exit 1
+    fi
+
+    local openrouter_key
+    openrouter_key="${OPENROUTER_API_KEY:-$(read_env_value OPENROUTER_API_KEY)}"
+
+    local response
+    if [[ -n "$openrouter_key" ]]; then
+        if ! response="$(curl -fsSL -H "Authorization: Bearer $openrouter_key" "$OPENROUTER_MODELS_URL")"; then
+            echo "Error: Failed to fetch OpenRouter models." >&2
+            exit 1
+        fi
+    else
+        if ! response="$(curl -fsSL "$OPENROUTER_MODELS_URL")"; then
+            echo "Error: Failed to fetch OpenRouter models." >&2
+            exit 1
+        fi
+    fi
+
+    parse_models_from_json <<< "$response"
+}
+
+get_lmstudio_models() {
+    if ! command -v curl >/dev/null 2>&1; then
+        echo "Error: curl is required for LM Studio model discovery." >&2
+        exit 1
+    fi
+
+    local lm_base
+    lm_base="${LM_STUDIO_BASE_URL:-$(read_env_value LM_STUDIO_BASE_URL)}"
+    lm_base="${lm_base:-$DEFAULT_LM_STUDIO_BASE_URL}"
+
+    local models_url
+    if [[ "$lm_base" == */v1 ]]; then
+        models_url="${lm_base}/models"
+    else
+        models_url="${lm_base}/v1/models"
+    fi
+
+    local response
+    if ! response="$(curl -fsSL "$models_url")"; then
+        echo "Error: Failed to query LM Studio models at $models_url" >&2
+        echo "Start LM Studio server first (Developer tab or: lms server start)." >&2
+        exit 1
+    fi
+
+    parse_models_from_json <<< "$response"
+}
+
+provider="${CLAUDE_PICK_PROVIDER:-$(read_env_value PROVIDER_TYPE)}"
+provider="${provider:-nvidia_nim}"
+
+prompt="Select a model> "
+case "$provider" in
+    nvidia_nim)
+        models="$(get_nvidia_models)"
+        prompt="Select a NVIDIA NIM model> "
+        ;;
+    open_router|openrouter)
+        models="$(get_openrouter_models)"
+        prompt="Select an OpenRouter model> "
+        ;;
+    lmstudio|lm_studio|lm-studio)
+        models="$(get_lmstudio_models)"
+        prompt="Select an LM Studio model> "
+        ;;
+    llamacpp|llama.cpp)
+        # llama.cpp doesn't have a standardized /models endpoint that returns all loaded models reliably
+        # in the same way, but it does support Anthropic routing. We can use a stub model or query if available.
+        # For simple picker, we'll just allow passing a default or typing it in, but to match fzf we offer a stub.
+        models="local-model\nllama-server"
+        prompt="Select a llama.cpp model> "
+        ;;
+    *)
+        echo "Error: Unsupported PROVIDER_TYPE='$provider'." >&2
+        echo "Expected one of: nvidia_nim, open_router, lmstudio, llamacpp" >&2
+        exit 1
+        ;;
+esac
+
+models="$(printf "%s\n" "$models" | sed '/^[[:space:]]*$/d' | sort -u)"
+if [[ -z "$models" ]]; then
+    echo "Error: No models found for provider '$provider'." >&2
+    exit 1
+fi
+
+model="$(printf "%s\n" "$models" | fzf --prompt="$prompt" --height=40% --reverse)"
+
+if [[ -z "${model:-}" ]]; then
+    echo "No model selected." >&2
+    exit 1
+fi
+
+# Read auth token from .env or environment
+auth_token="${ANTHROPIC_AUTH_TOKEN:-$(read_env_value ANTHROPIC_AUTH_TOKEN)}"
+if [[ -z "$auth_token" ]]; then
+    auth_token="freecc"
+fi
+
+# If auth_token doesn't contain a colon, append ":$model"
+if [[ "$auth_token" != *:* ]]; then
+    auth_token="$auth_token:$model"
+fi
+
+echo "Launching Claude with provider: $provider, model: $model" >&2
+ANTHROPIC_AUTH_TOKEN="$auth_token" ANTHROPIC_BASE_URL="$BASE_URL" exec claude "$@"

Claude_Code/cli/__init__.py

@@ -0,0 +1,6 @@
+"""CLI integration for Claude Code."""
+
+from .manager import CLISessionManager
+from .session import CLISession
+
+__all__ = ["CLISession", "CLISessionManager"]

Claude_Code/cli/entrypoints.py

@@ -0,0 +1,47 @@
+"""CLI entry points for the installed package."""
+
+from __future__ import annotations
+
+
+def serve() -> None:
+    """Start the FastAPI server (registered as `free-claude-code` script)."""
+    import uvicorn
+
+    from cli.process_registry import kill_all_best_effort
+    from config.settings import get_settings
+
+    settings = get_settings()
+    try:
+        uvicorn.run(
+            "api.app:app",
+            host=settings.host,
+            port=settings.port,
+            log_level="debug",
+            timeout_graceful_shutdown=5,
+        )
+    finally:
+        kill_all_best_effort()
+
+
+def init() -> None:
+    """Scaffold config at ~/.config/free-claude-code/.env (registered as `fcc-init`)."""
+    import importlib.resources
+    from pathlib import Path
+
+    config_dir = Path.home() / ".config" / "free-claude-code"
+    env_file = config_dir / ".env"
+
+    if env_file.exists():
+        print(f"Config already exists at {env_file}")
+        print("Delete it first if you want to reset to defaults.")
+        return
+
+    config_dir.mkdir(parents=True, exist_ok=True)
+    template = (
+        importlib.resources.files("config").joinpath("env.example").read_text("utf-8")
+    )
+    env_file.write_text(template, encoding="utf-8")
+    print(f"Config created at {env_file}")
+    print(
+        "Edit it to set your API keys and model preferences, then run: free-claude-code"
+    )

Claude_Code/cli/manager.py

@@ -0,0 +1,144 @@
+"""
+CLI Session Manager for Multi-Instance Claude CLI Support
+
+Manages a pool of CLISession instances, each handling one conversation.
+This enables true parallel processing where multiple conversations run
+simultaneously in separate CLI processes.
+"""
+
+import asyncio
+import uuid
+
+from loguru import logger
+
+from .session import CLISession
+
+
+class CLISessionManager:
+    """
+    Manages multiple CLISession instances for parallel conversation processing.
+
+    Each new conversation gets its own CLISession with its own subprocess.
+    Replies to existing conversations reuse the same CLISession instance.
+    """
+
+    def __init__(
+        self,
+        workspace_path: str,
+        api_url: str,
+        allowed_dirs: list[str] | None = None,
+        plans_directory: str | None = None,
+    ):
+        """
+        Initialize the session manager.
+
+        Args:
+            workspace_path: Working directory for CLI processes
+            api_url: API URL for the proxy
+            allowed_dirs: Directories the CLI is allowed to access
+            plans_directory: Directory for Claude Code CLI plan files (passed via --settings)
+        """
+        self.workspace = workspace_path
+        self.api_url = api_url
+        self.allowed_dirs = allowed_dirs or []
+        self.plans_directory = plans_directory
+
+        self._sessions: dict[str, CLISession] = {}
+        self._pending_sessions: dict[str, CLISession] = {}
+        self._temp_to_real: dict[str, str] = {}
+        self._real_to_temp: dict[str, str] = {}
+        self._lock = asyncio.Lock()
+
+        logger.info("CLISessionManager initialized")
+
+    async def get_or_create_session(
+        self, session_id: str | None = None
+    ) -> tuple[CLISession, str, bool]:
+        """
+        Get an existing session or create a new one.
+
+        Returns:
+            Tuple of (CLISession instance, session_id, is_new_session)
+        """
+        async with self._lock:
+            if session_id:
+                lookup_id = self._temp_to_real.get(session_id, session_id)
+
+                if lookup_id in self._sessions:
+                    return self._sessions[lookup_id], lookup_id, False
+                if lookup_id in self._pending_sessions:
+                    return self._pending_sessions[lookup_id], lookup_id, False
+
+            temp_id = session_id if session_id else f"pending_{uuid.uuid4().hex[:8]}"
+
+            new_session = CLISession(
+                workspace_path=self.workspace,
+                api_url=self.api_url,
+                allowed_dirs=self.allowed_dirs,
+                plans_directory=self.plans_directory,
+            )
+            self._pending_sessions[temp_id] = new_session
+            logger.info(f"Created new session: {temp_id}")
+
+            return new_session, temp_id, True
+
+    async def register_real_session_id(
+        self, temp_id: str, real_session_id: str
+    ) -> bool:
+        """Register the real session ID from CLI output."""
+        async with self._lock:
+            if temp_id not in self._pending_sessions:
+                logger.warning(f"Temp session {temp_id} not found")
+                return False
+
+            session = self._pending_sessions.pop(temp_id)
+            self._sessions[real_session_id] = session
+            self._temp_to_real[temp_id] = real_session_id
+            self._real_to_temp[real_session_id] = temp_id
+
+            logger.info(f"Registered session: {temp_id} -> {real_session_id}")
+            return True
+
+    async def remove_session(self, session_id: str) -> bool:
+        """Remove a session from the manager."""
+        async with self._lock:
+            if session_id in self._pending_sessions:
+                session = self._pending_sessions.pop(session_id)
+                await session.stop()
+                return True
+
+            if session_id in self._sessions:
+                session = self._sessions.pop(session_id)
+                await session.stop()
+                temp_id = self._real_to_temp.pop(session_id, None)
+                if temp_id is not None:
+                    self._temp_to_real.pop(temp_id, None)
+                return True
+
+            return False
+
+    async def stop_all(self):
+        """Stop all sessions."""
+        async with self._lock:
+            all_sessions = list(self._sessions.values()) + list(
+                self._pending_sessions.values()
+            )
+            for session in all_sessions:
+                try:
+                    await session.stop()
+                except Exception as e:
+                    logger.error(f"Error stopping session: {e}")
+
+            self._sessions.clear()
+            self._pending_sessions.clear()
+            self._temp_to_real.clear()
+            self._real_to_temp.clear()
+            logger.info("All sessions stopped")
+
+    def get_stats(self) -> dict:
+        """Get session statistics."""
+        return {
+            "active_sessions": len(self._sessions),
+            "pending_sessions": len(self._pending_sessions),
+            "busy_count": sum(1 for s in self._sessions.values() if s.is_busy),
+        }

Claude_Code/cli/process_registry.py

@@ -0,0 +1,74 @@
+"""Track and clean up spawned CLI subprocesses.
+
+This is a safety net for cases where the server is interrupted (Ctrl+C) and the
+FastAPI lifespan cleanup doesn't run to completion. We only track processes we
+spawn so we don't accidentally kill unrelated system processes.
+"""
+
+from __future__ import annotations
+
+import atexit
+import os
+import subprocess
+import threading
+
+from loguru import logger
+
+_lock = threading.Lock()
+_pids: set[int] = set()
+_atexit_registered = False
+
+
+def ensure_atexit_registered() -> None:
+    global _atexit_registered
+    with _lock:
+        if _atexit_registered:
+            return
+        atexit.register(kill_all_best_effort)
+        _atexit_registered = True
+
+
+def register_pid(pid: int) -> None:
+    if not pid:
+        return
+    ensure_atexit_registered()
+    with _lock:
+        _pids.add(int(pid))
+
+
+def unregister_pid(pid: int) -> None:
+    if not pid:
+        return
+    with _lock:
+        _pids.discard(int(pid))
+
+
+def kill_all_best_effort() -> None:
+    """Kill any still-running registered pids (best-effort)."""
+    with _lock:
+        pids = list(_pids)
+        _pids.clear()
+
+    if not pids:
+        return
+
+    if os.name == "nt":
+        for pid in pids:
+            try:
+                # /T kills child processes, /F forces termination.
+                subprocess.run(
+                    ["taskkill", "/PID", str(pid), "/T", "/F"],
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    check=False,
+                )
+            except Exception as e:
+                logger.debug("process_registry: taskkill failed pid=%s: %s", pid, e)
+        return
+
+    # Best-effort fallback for non-Windows.
+    for pid in pids:
+        try:
+            os.kill(pid, 9)
+        except Exception as e:
+            logger.debug("process_registry: kill failed pid=%s: %s", pid, e)

Claude_Code/cli/session.py

@@ -0,0 +1,257 @@
+"""Claude Code CLI session management."""
+
+import asyncio
+import json
+import os
+from collections.abc import AsyncGenerator
+from typing import Any
+
+from loguru import logger
+
+from .process_registry import register_pid, unregister_pid
+
+
+class CLISession:
+    """Manages a single persistent Claude Code CLI subprocess."""
+
+    def __init__(
+        self,
+        workspace_path: str,
+        api_url: str,
+        allowed_dirs: list[str] | None = None,
+        plans_directory: str | None = None,
+    ):
+        self.workspace = os.path.normpath(os.path.abspath(workspace_path))
+        self.api_url = api_url
+        self.allowed_dirs = [os.path.normpath(d) for d in (allowed_dirs or [])]
+        self.plans_directory = plans_directory
+        self.process: asyncio.subprocess.Process | None = None
+        self.current_session_id: str | None = None
+        self._is_busy = False
+        self._cli_lock = asyncio.Lock()
+
+    @property
+    def is_busy(self) -> bool:
+        """Check if a task is currently running."""
+        return self._is_busy
+
+    async def start_task(
+        self, prompt: str, session_id: str | None = None, fork_session: bool = False
+    ) -> AsyncGenerator[dict]:
+        """
+        Start a new task or continue an existing session.
+
+        Args:
+            prompt: The user's message/prompt
+            session_id: Optional session ID to resume
+
+        Yields:
+            Event dictionaries from the CLI
+        """
+        async with self._cli_lock:
+            self._is_busy = True
+            env = os.environ.copy()
+
+            if "ANTHROPIC_API_KEY" not in env:
+                env["ANTHROPIC_API_KEY"] = "sk-placeholder-key-for-proxy"
+
+            env["ANTHROPIC_API_URL"] = self.api_url
+            if self.api_url.endswith("/v1"):
+                env["ANTHROPIC_BASE_URL"] = self.api_url[:-3]
+            else:
+                env["ANTHROPIC_BASE_URL"] = self.api_url
+
+            env["TERM"] = "dumb"
+            env["PYTHONIOENCODING"] = "utf-8"
+
+            # Build command
+            if session_id and not session_id.startswith("pending_"):
+                cmd = [
+                    "claude",
+                    "--resume",
+                    session_id,
+                ]
+                if fork_session:
+                    cmd.append("--fork-session")
+                cmd += [
+                    "-p",
+                    prompt,
+                    "--output-format",
+                    "stream-json",
+                    "--dangerously-skip-permissions",
+                    "--verbose",
+                ]
+                logger.info(f"Resuming Claude session {session_id}")
+            else:
+                cmd = [
+                    "claude",
+                    "-p",
+                    prompt,
+                    "--output-format",
+                    "stream-json",
+                    "--dangerously-skip-permissions",
+                    "--verbose",
+                ]
+                logger.info("Starting new Claude session")
+
+            if self.allowed_dirs:
+                for d in self.allowed_dirs:
+                    cmd.extend(["--add-dir", d])
+
+            if self.plans_directory is not None:
+                settings_json = json.dumps({"plansDirectory": self.plans_directory})
+                cmd.extend(["--settings", settings_json])
+
+            try:
+                self.process = await asyncio.create_subprocess_exec(
+                    *cmd,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.PIPE,
+                    cwd=self.workspace,
+                    env=env,
+                )
+                if self.process and self.process.pid:
+                    register_pid(self.process.pid)
+
+                if not self.process or not self.process.stdout:
+                    yield {"type": "exit", "code": 1}
+                    return
+
+                session_id_extracted = False
+                buffer = bytearray()
+
+                try:
+                    while True:
+                        chunk = await self.process.stdout.read(65536)
+                        if not chunk:
+                            if buffer:
+                                line_str = buffer.decode(
+                                    "utf-8", errors="replace"
+                                ).strip()
+                                if line_str:
+                                    async for event in self._handle_line_gen(
+                                        line_str, session_id_extracted
+                                    ):
+                                        if event.get("type") == "session_info":
+                                            session_id_extracted = True
+                                        yield event
+                            break
+
+                        buffer.extend(chunk)
+
+                        while True:
+                            newline_pos = buffer.find(b"\n")
+                            if newline_pos == -1:
+                                break
+
+                            line = buffer[:newline_pos]
+                            buffer = buffer[newline_pos + 1 :]
+
+                            line_str = line.decode("utf-8", errors="replace").strip()
+                            if line_str:
+                                async for event in self._handle_line_gen(
+                                    line_str, session_id_extracted
+                                ):
+                                    if event.get("type") == "session_info":
+                                        session_id_extracted = True
+                                    yield event
+                except asyncio.CancelledError:
+                    # Cancelling the handler task should not leave a Claude CLI
+                    # subprocess running in the background.
+                    try:
+                        await asyncio.shield(self.stop())
+                    finally:
+                        raise
+
+                stderr_text = None
+                if self.process.stderr:
+                    stderr_output = await self.process.stderr.read()
+                    if stderr_output:
+                        stderr_text = stderr_output.decode(
+                            "utf-8", errors="replace"
+                        ).strip()
+                        logger.error(f"Claude CLI Stderr: {stderr_text}")
+                        # Yield stderr as error event so it shows in UI
+                        if stderr_text:
+                            logger.info("CLI_SESSION: Yielding error event from stderr")
+                            yield {"type": "error", "error": {"message": stderr_text}}
+
+                return_code = await self.process.wait()
+                logger.info(
+                    f"Claude CLI exited with code {return_code}, stderr_present={bool(stderr_text)}"
+                )
+                if return_code != 0 and not stderr_text:
+                    logger.warning(
+                        f"CLI_SESSION: Process exited with code {return_code} but no stderr captured"
+                    )
+                yield {
+                    "type": "exit",
+                    "code": return_code,
+                    "stderr": stderr_text,
+                }
+            finally:
+                self._is_busy = False
+                if self.process and self.process.pid:
+                    unregister_pid(self.process.pid)
+
+    async def _handle_line_gen(
+        self, line_str: str, session_id_extracted: bool
+    ) -> AsyncGenerator[dict]:
+        """Process a single line and yield events."""
+        try:
+            event = json.loads(line_str)
+            if not session_id_extracted:
+                extracted_id = self._extract_session_id(event)
+                if extracted_id:
+                    self.current_session_id = extracted_id
+                    logger.info(f"Extracted session ID: {extracted_id}")
+                    yield {"type": "session_info", "session_id": extracted_id}
+
+            yield event
+        except json.JSONDecodeError:
+            logger.debug(f"Non-JSON output: {line_str}")
+            yield {"type": "raw", "content": line_str}
+
+    def _extract_session_id(self, event: Any) -> str | None:
+        """Extract session ID from CLI event."""
+        if not isinstance(event, dict):
+            return None
+
+        if "session_id" in event:
+            return event["session_id"]
+        if "sessionId" in event:
+            return event["sessionId"]
+
+        for key in ["init", "system", "result", "metadata"]:
+            if key in event and isinstance(event[key], dict):
+                nested = event[key]
+                if "session_id" in nested:
+                    return nested["session_id"]
+                if "sessionId" in nested:
+                    return nested["sessionId"]
+
+        if "conversation" in event and isinstance(event["conversation"], dict):
+            conv = event["conversation"]
+            if "id" in conv:
+                return conv["id"]
+
+        return None
+
+    async def stop(self):
+        """Stop the CLI process."""
+        if self.process and self.process.returncode is None:
+            try:
+                logger.info(f"Stopping Claude CLI process {self.process.pid}")
+                self.process.terminate()
+                try:
+                    await asyncio.wait_for(self.process.wait(), timeout=5.0)
+                except TimeoutError:
+                    self.process.kill()
+                    await self.process.wait()
+                if self.process and self.process.pid:
+                    unregister_pid(self.process.pid)
+                return True
+            except Exception as e:
+                logger.error(f"Error stopping process: {e}")
+                return False
+        return False

Claude_Code/config/__init__.py

@@ -0,0 +1,5 @@
+"""Configuration management."""
+
+from .settings import Settings, get_settings
+
+__all__ = ["Settings", "get_settings"]

Claude_Code/config/env.example

@@ -0,0 +1,71 @@
+# NVIDIA NIM Config
+NVIDIA_NIM_API_KEY=""
+
+
+# OpenRouter Config
+OPENROUTER_API_KEY=""
+
+
+# LM Studio Config (local provider, no API key required)
+LM_STUDIO_BASE_URL="http://localhost:1234/v1"
+
+
+# All Claude model requests are mapped to these models, plain model is fallback
+# Format: provider_type/model/name
+# Valid providers: "nvidia_nim" | "open_router" | "lmstudio"
+MODEL_OPUS="nvidia_nim/z-ai/glm4.7"
+MODEL_SONNET="open_router/arcee-ai/trinity-large-preview:free"
+MODEL_HAIKU="open_router/stepfun/step-3.5-flash:free"
+MODEL="nvidia_nim/z-ai/glm4.7"
+
+
+# Provider config
+PROVIDER_RATE_LIMIT=40
+PROVIDER_RATE_WINDOW=60
+PROVIDER_MAX_CONCURRENCY=5
+
+
+# HTTP client timeouts (seconds) for provider API requests
+HTTP_READ_TIMEOUT=120
+HTTP_WRITE_TIMEOUT=10
+HTTP_CONNECT_TIMEOUT=2
+
+
+# Messaging Platform: "telegram" | "discord"
+MESSAGING_PLATFORM="discord"
+MESSAGING_RATE_LIMIT=1
+MESSAGING_RATE_WINDOW=1
+
+
+# Voice Note Transcription
+VOICE_NOTE_ENABLED=false
+# WHISPER_DEVICE: "cpu" | "cuda" | "nvidia_nim"
+# - "cpu"/"cuda": Hugging Face transformers Whisper (offline, free; install with: uv sync --extra voice_local)
+# - "nvidia_nim": NVIDIA NIM Whisper via Riva gRPC (requires NVIDIA_NIM_API_KEY; install with: uv sync --extra voice)
+WHISPER_DEVICE="nvidia_nim"
+# WHISPER_MODEL:
+# - For cpu/cuda: Hugging Face ID or short name (tiny, base, small, medium, large-v2, large-v3, large-v3-turbo)
+# - For nvidia_nim: NVIDIA NIM model (e.g., "nvidia/parakeet-ctc-1.1b-asr", "openai/whisper-large-v3")
+# - For nvidia_nim, default to "openai/whisper-large-v3" for best performance
+WHISPER_MODEL="openai/whisper-large-v3"
+HF_TOKEN=""
+
+
+# Telegram Config
+TELEGRAM_BOT_TOKEN=""
+ALLOWED_TELEGRAM_USER_ID=""
+
+
+# Discord Config
+DISCORD_BOT_TOKEN=""
+ALLOWED_DISCORD_CHANNELS=""
+
+
+# Agent Config
+CLAUDE_WORKSPACE="./agent_workspace"
+ALLOWED_DIR=""
+FAST_PREFIX_DETECTION=true
+ENABLE_NETWORK_PROBE_MOCK=true
+ENABLE_TITLE_GENERATION_SKIP=true
+ENABLE_SUGGESTION_MODE_SKIP=true
+ENABLE_FILEPATH_EXTRACTION_MOCK=true

Claude_Code/config/logging_config.py

@@ -0,0 +1,90 @@
+"""Loguru-based structured logging configuration.
+
+All logs are written to server.log as JSON lines for full traceability.
+Stdlib logging is intercepted and funneled to loguru.
+Context vars (request_id, node_id, chat_id) from contextualize() are
+included at top level for easy grep/filter.
+"""
+
+import json
+import logging
+from pathlib import Path
+
+from loguru import logger
+
+_configured = False
+
+# Context keys we promote to top-level JSON for traceability
+_CONTEXT_KEYS = ("request_id", "node_id", "chat_id")
+
+
+def _serialize_with_context(record) -> str:
+    """Format record as JSON with context vars at top level.
+    Returns a format template; we inject _json into record for output.
+    """
+    extra = record.get("extra", {})
+    out = {
+        "time": str(record["time"]),
+        "level": record["level"].name,
+        "message": record["message"],
+        "module": record["name"],
+        "function": record["function"],
+        "line": record["line"],
+    }
+    for key in _CONTEXT_KEYS:
+        if key in extra and extra[key] is not None:
+            out[key] = extra[key]
+    record["_json"] = json.dumps(out, default=str)
+    return "{_json}\n"
+
+
+class InterceptHandler(logging.Handler):
+    """Redirect stdlib logging to loguru."""
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            level = logger.level(record.levelname).name
+        except ValueError:
+            level = record.levelno
+
+        frame, depth = logging.currentframe(), 2
+        while frame is not None and frame.f_code.co_filename == logging.__file__:
+            frame = frame.f_back
+            depth += 1
+
+        logger.opt(depth=depth, exception=record.exc_info).log(
+            level, record.getMessage()
+        )
+
+
+def configure_logging(log_file: str, *, force: bool = False) -> None:
+    """Configure loguru with JSON output to log_file and intercept stdlib logging.
+
+    Idempotent: skips if already configured (e.g. hot reload).
+    Use force=True to reconfigure (e.g. in tests with a different log path).
+    """
+    global _configured
+    if _configured and not force:
+        return
+    _configured = True
+
+    # Remove default loguru handler (writes to stderr)
+    logger.remove()
+
+    # Truncate log file on fresh start for clean debugging
+    Path(log_file).write_text("")
+
+    # Add file sink: JSON lines, DEBUG level, context vars at top level
+    logger.add(
+        log_file,
+        level="DEBUG",
+        format=_serialize_with_context,
+        encoding="utf-8",
+        mode="a",
+        rotation="50 MB",
+    )
+
+    # Intercept stdlib logging: route all root logger output to loguru
+    intercept = InterceptHandler()
+    logging.root.handlers = [intercept]
+    logging.root.setLevel(logging.DEBUG)

Claude_Code/config/nim.py

@@ -0,0 +1,51 @@
+"""NVIDIA NIM settings (fixed values, no env config)."""
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class NimSettings(BaseModel):
+    """Fixed NVIDIA NIM settings (not configurable via env)."""
+
+    temperature: float = Field(1.0, ge=0.0)
+    top_p: float = Field(1.0, ge=0.0, le=1.0)
+    top_k: int = -1
+    max_tokens: int = Field(81920, ge=1)
+    presence_penalty: float = Field(0.0, ge=-2.0, le=2.0)
+    frequency_penalty: float = Field(0.0, ge=-2.0, le=2.0)
+
+    min_p: float = Field(0.0, ge=0.0, le=1.0)
+    repetition_penalty: float = Field(1.0, ge=0.0)
+
+    seed: int | None = None
+    stop: str | None = None
+
+    parallel_tool_calls: bool = True
+    ignore_eos: bool = False
+    enable_thinking: bool = False
+
+    min_tokens: int = Field(0, ge=0)
+    chat_template: str | None = None
+    request_id: str | None = None
+
+    model_config = ConfigDict(extra="forbid")
+
+    @field_validator("top_k")
+    @classmethod
+    def validate_top_k(cls, v):
+        if v < -1:
+            raise ValueError("top_k must be -1 or >= 0")
+        return v
+
+    @field_validator("seed", mode="before")
+    @classmethod
+    def parse_optional_int(cls, v):
+        if v == "" or v is None:
+            return None
+        return int(v)
+
+    @field_validator("stop", "chat_template", "request_id", mode="before")
+    @classmethod
+    def parse_optional_str(cls, v):
+        if v == "":
+            return None
+        return v

Claude_Code/config/settings.py

@@ -0,0 +1,242 @@
+"""Centralized configuration using Pydantic Settings."""
+
+import os
+from functools import lru_cache
+from pathlib import Path
+
+from pydantic import Field, field_validator, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from .nim import NimSettings
+
+
+def _env_files() -> tuple[Path, ...]:
+    """Return env file paths in priority order (later overrides earlier)."""
+    files: list[Path] = [
+        Path.home() / ".config" / "free-claude-code" / ".env",
+        Path(".env"),
+    ]
+    if explicit := os.environ.get("FCC_ENV_FILE"):
+        files.append(Path(explicit))
+    return tuple(files)
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables."""
+
+    # ==================== OpenRouter Config ====================
+    open_router_api_key: str = Field(default="", validation_alias="OPENROUTER_API_KEY")
+
+    # ==================== Messaging Platform Selection ====================
+    # Valid: "telegram" | "discord"
+    messaging_platform: str = Field(
+        default="discord", validation_alias="MESSAGING_PLATFORM"
+    )
+
+    # ==================== NVIDIA NIM Config ====================
+    nvidia_nim_api_key: str = ""
+
+    # ==================== LM Studio Config ====================
+    lm_studio_base_url: str = Field(
+        default="http://localhost:1234/v1",
+        validation_alias="LM_STUDIO_BASE_URL",
+    )
+
+    # ==================== Llama.cpp Config ====================
+    llamacpp_base_url: str = Field(
+        default="http://localhost:8080/v1",
+        validation_alias="LLAMACPP_BASE_URL",
+    )
+
+    # ==================== Model ====================
+    # All Claude model requests are mapped to this single model (fallback)
+    # Format: provider_type/model/name
+    model: str = "nvidia_nim/meta/llama3-70b-instruct"
+
+    # Per-model overrides (optional, falls back to MODEL)
+    # Each can use a different provider
+    model_opus: str | None = Field(default=None, validation_alias="MODEL_OPUS")
+    model_sonnet: str | None = Field(default=None, validation_alias="MODEL_SONNET")
+    model_haiku: str | None = Field(default=None, validation_alias="MODEL_HAIKU")
+
+    # ==================== Provider Rate Limiting ====================
+    provider_rate_limit: int = Field(default=40, validation_alias="PROVIDER_RATE_LIMIT")
+    provider_rate_window: int = Field(
+        default=60, validation_alias="PROVIDER_RATE_WINDOW"
+    )
+    provider_max_concurrency: int = Field(
+        default=5, validation_alias="PROVIDER_MAX_CONCURRENCY"
+    )
+
+    # ==================== HTTP Client Timeouts ====================
+    http_read_timeout: float = Field(
+        default=300.0, validation_alias="HTTP_READ_TIMEOUT"
+    )
+    http_write_timeout: float = Field(
+        default=10.0, validation_alias="HTTP_WRITE_TIMEOUT"
+    )
+    http_connect_timeout: float = Field(
+        default=2.0, validation_alias="HTTP_CONNECT_TIMEOUT"
+    )
+
+    # ==================== Fast Prefix Detection ====================
+    fast_prefix_detection: bool = True
+
+    # ==================== Optimizations ====================
+    enable_network_probe_mock: bool = True
+    enable_title_generation_skip: bool = True
+    enable_suggestion_mode_skip: bool = True
+    enable_filepath_extraction_mock: bool = True
+
+    # ==================== NIM Settings ====================
+    nim: NimSettings = Field(default_factory=NimSettings)
+    nim_enable_thinking: bool = Field(
+        default=False, validation_alias="NIM_ENABLE_THINKING"
+    )
+
+    # ==================== Voice Note Transcription ====================
+    voice_note_enabled: bool = Field(
+        default=True, validation_alias="VOICE_NOTE_ENABLED"
+    )
+    # Device: "cpu" | "cuda" | "nvidia_nim"
+    # - "cpu"/"cuda": local Whisper (requires voice_local extra: uv sync --extra voice_local)
+    # - "nvidia_nim": NVIDIA NIM Whisper API (requires voice extra: uv sync --extra voice)
+    whisper_device: str = Field(default="cpu", validation_alias="WHISPER_DEVICE")
+    # Whisper model ID or short name (for local Whisper) or NVIDIA NIM model (for nvidia_nim)
+    # Local Whisper: "tiny", "base", "small", "medium", "large-v2", "large-v3", "large-v3-turbo"
+    # NVIDIA NIM: "nvidia/parakeet-ctc-1.1b-asr", "openai/whisper-large-v3", etc.
+    whisper_model: str = Field(default="base", validation_alias="WHISPER_MODEL")
+    # Hugging Face token for faster model downloads (optional, for local Whisper)
+    hf_token: str = Field(default="", validation_alias="HF_TOKEN")
+
+    # ==================== Bot Wrapper Config ====================
+    telegram_bot_token: str | None = None
+    allowed_telegram_user_id: str | None = None
+    discord_bot_token: str | None = Field(
+        default=None, validation_alias="DISCORD_BOT_TOKEN"
+    )
+    allowed_discord_channels: str | None = Field(
+        default=None, validation_alias="ALLOWED_DISCORD_CHANNELS"
+    )
+    claude_workspace: str = "./agent_workspace"
+    allowed_dir: str = ""
+
+    # ==================== Server ====================
+    host: str = "0.0.0.0"
+    port: int = 8082
+    log_file: str = "server.log"
+    # Optional server API key to protect endpoints (Anthropic-style)
+    # Set via env `ANTHROPIC_AUTH_TOKEN`. When empty, no auth is required.
+    anthropic_auth_token: str = Field(
+        default="", validation_alias="ANTHROPIC_AUTH_TOKEN"
+    )
+
+    # Handle empty strings for optional string fields
+    @field_validator(
+        "telegram_bot_token",
+        "allowed_telegram_user_id",
+        "discord_bot_token",
+        "allowed_discord_channels",
+        mode="before",
+    )
+    @classmethod
+    def parse_optional_str(cls, v):
+        if v == "":
+            return None
+        return v
+
+    @field_validator("whisper_device")
+    @classmethod
+    def validate_whisper_device(cls, v: str) -> str:
+        if v not in ("cpu", "cuda", "nvidia_nim"):
+            raise ValueError(
+                f"whisper_device must be 'cpu', 'cuda', or 'nvidia_nim', got {v!r}"
+            )
+        return v
+
+    @field_validator("model", "model_opus", "model_sonnet", "model_haiku")
+    @classmethod
+    def validate_model_format(cls, v: str | None) -> str | None:
+        if v is None:
+            return None
+        valid_providers = ("nvidia_nim", "open_router", "lmstudio", "llamacpp")
+        if "/" not in v:
+            raise ValueError(
+                f"Model must be prefixed with provider type. "
+                f"Valid providers: {', '.join(valid_providers)}. "
+                f"Format: provider_type/model/name"
+            )
+        provider = v.split("/", 1)[0]
+        if provider not in valid_providers:
+            raise ValueError(
+                f"Invalid provider: '{provider}'. "
+                f"Supported: 'nvidia_nim', 'open_router', 'lmstudio', 'llamacpp'"
+            )
+        return v
+
+    @model_validator(mode="after")
+    def _inject_nim_thinking(self) -> "Settings":
+        self.nim = self.nim.model_copy(
+            update={"enable_thinking": self.nim_enable_thinking}
+        )
+        return self
+
+    @model_validator(mode="after")
+    def check_nvidia_nim_api_key(self) -> "Settings":
+        if (
+            self.voice_note_enabled
+            and self.whisper_device == "nvidia_nim"
+            and not self.nvidia_nim_api_key.strip()
+        ):
+            raise ValueError(
+                "NVIDIA_NIM_API_KEY is required when WHISPER_DEVICE is 'nvidia_nim'. "
+                "Set it in your .env file."
+            )
+        return self
+
+    @property
+    def provider_type(self) -> str:
+        """Extract provider type from the default model string."""
+        return self.model.split("/", 1)[0]
+
+    @property
+    def model_name(self) -> str:
+        """Extract the actual model name from the default model string."""
+        return self.model.split("/", 1)[1]
+
+    def resolve_model(self, claude_model_name: str) -> str:
+        """Resolve a Claude model name to the configured provider/model string.
+
+        Classifies the incoming Claude model (opus/sonnet/haiku) and
+        returns the model-specific override if configured, otherwise the fallback MODEL.
+        """
+        name_lower = claude_model_name.lower()
+        if "opus" in name_lower and self.model_opus is not None:
+            return self.model_opus
+        if "haiku" in name_lower and self.model_haiku is not None:
+            return self.model_haiku
+        if "sonnet" in name_lower and self.model_sonnet is not None:
+            return self.model_sonnet
+        return self.model
+
+    @staticmethod
+    def parse_provider_type(model_string: str) -> str:
+        """Extract provider type from any 'provider/model' string."""
+        return model_string.split("/", 1)[0]
+
+    @staticmethod
+    def parse_model_name(model_string: str) -> str:
+        """Extract model name from any 'provider/model' string."""
+        return model_string.split("/", 1)[1]
+
+    model_config = SettingsConfigDict(
+        env_file=_env_files(),
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """Get cached settings instance."""
+    return Settings()

Claude_Code/messaging/__init__.py

@@ -0,0 +1,23 @@
+"""Platform-agnostic messaging layer."""
+
+from .event_parser import parse_cli_event
+from .handler import ClaudeMessageHandler
+from .models import IncomingMessage
+from .platforms.base import CLISession, MessagingPlatform, SessionManagerInterface
+from .session import SessionStore
+from .trees.data import MessageNode, MessageState, MessageTree
+from .trees.queue_manager import TreeQueueManager
+
+__all__ = [
+    "CLISession",
+    "ClaudeMessageHandler",
+    "IncomingMessage",
+    "MessageNode",
+    "MessageState",
+    "MessageTree",
+    "MessagingPlatform",
+    "SessionManagerInterface",
+    "SessionStore",
+    "TreeQueueManager",
+    "parse_cli_event",
+]

Claude_Code/messaging/commands.py

@@ -0,0 +1,283 @@
+"""Command handlers for messaging platform commands (/stop, /stats, /clear).
+
+Extracted from ClaudeMessageHandler to keep handler.py focused on
+core message processing logic.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from loguru import logger
+
+if TYPE_CHECKING:
+    from messaging.handler import ClaudeMessageHandler
+    from messaging.models import IncomingMessage
+
+
+async def handle_stop_command(
+    handler: ClaudeMessageHandler, incoming: IncomingMessage
+) -> None:
+    """Handle /stop command from messaging platform."""
+    # Reply-scoped stop: reply "/stop" to stop only that task.
+    if incoming.is_reply() and incoming.reply_to_message_id:
+        reply_id = incoming.reply_to_message_id
+        tree = handler.tree_queue.get_tree_for_node(reply_id)
+        node_id = handler.tree_queue.resolve_parent_node_id(reply_id) if tree else None
+
+        if not node_id:
+            msg_id = await handler.platform.queue_send_message(
+                incoming.chat_id,
+                handler.format_status(
+                    "⏹", "Stopped.", "Nothing to stop for that message."
+                ),
+                fire_and_forget=False,
+                message_thread_id=incoming.message_thread_id,
+            )
+            handler.record_outgoing_message(
+                incoming.platform, incoming.chat_id, msg_id, "command"
+            )
+            return
+
+        count = await handler.stop_task(node_id)
+        noun = "request" if count == 1 else "requests"
+        msg_id = await handler.platform.queue_send_message(
+            incoming.chat_id,
+            handler.format_status("⏹", "Stopped.", f"Cancelled {count} {noun}."),
+            fire_and_forget=False,
+            message_thread_id=incoming.message_thread_id,
+        )
+        handler.record_outgoing_message(
+            incoming.platform, incoming.chat_id, msg_id, "command"
+        )
+        return
+
+    # Global stop: legacy behavior (stop everything)
+    count = await handler.stop_all_tasks()
+    msg_id = await handler.platform.queue_send_message(
+        incoming.chat_id,
+        handler.format_status(
+            "⏹", "Stopped.", f"Cancelled {count} pending or active requests."
+        ),
+        fire_and_forget=False,
+        message_thread_id=incoming.message_thread_id,
+    )
+    handler.record_outgoing_message(
+        incoming.platform, incoming.chat_id, msg_id, "command"
+    )
+
+
+async def handle_stats_command(
+    handler: ClaudeMessageHandler, incoming: IncomingMessage
+) -> None:
+    """Handle /stats command."""
+    stats = handler.cli_manager.get_stats()
+    tree_count = handler.tree_queue.get_tree_count()
+    ctx = handler.get_render_ctx()
+    msg_id = await handler.platform.queue_send_message(
+        incoming.chat_id,
+        "📊 "
+        + ctx.bold("Stats")
+        + "\n"
+        + ctx.escape_text(f"• Active CLI: {stats['active_sessions']}")
+        + "\n"
+        + ctx.escape_text(f"• Message Trees: {tree_count}"),
+        fire_and_forget=False,
+        message_thread_id=incoming.message_thread_id,
+    )
+    handler.record_outgoing_message(
+        incoming.platform, incoming.chat_id, msg_id, "command"
+    )
+
+
+async def _delete_message_ids(
+    handler: ClaudeMessageHandler, chat_id: str, msg_ids: set[str]
+) -> None:
+    """Best-effort delete messages by ID. Sorts numeric IDs descending."""
+    if not msg_ids:
+        return
+
+    def _as_int(s: str) -> int | None:
+        try:
+            return int(str(s))
+        except Exception:
+            return None
+
+    numeric: list[tuple[int, str]] = []
+    non_numeric: list[str] = []
+    for mid in msg_ids:
+        n = _as_int(mid)
+        if n is None:
+            non_numeric.append(mid)
+        else:
+            numeric.append((n, mid))
+    numeric.sort(reverse=True)
+    ordered = [mid for _, mid in numeric] + non_numeric
+
+    batch_fn = getattr(handler.platform, "queue_delete_messages", None)
+    if callable(batch_fn):
+        try:
+            CHUNK = 100
+            for i in range(0, len(ordered), CHUNK):
+                chunk = ordered[i : i + CHUNK]
+                await batch_fn(chat_id, chunk, fire_and_forget=False)
+        except Exception as e:
+            logger.debug(f"Batch delete failed: {type(e).__name__}: {e}")
+    else:
+        for mid in ordered:
+            try:
+                await handler.platform.queue_delete_message(
+                    chat_id, mid, fire_and_forget=False
+                )
+            except Exception as e:
+                logger.debug(f"Delete failed for msg {mid}: {type(e).__name__}: {e}")
+
+
+async def _handle_clear_branch(
+    handler: ClaudeMessageHandler,
+    incoming: IncomingMessage,
+    branch_root_id: str,
+) -> None:
+    """
+    Clear a branch (replied-to node + all descendants).
+
+    Order: cancel tasks, delete messages, remove branch, update session store.
+    """
+    tree = handler.tree_queue.get_tree_for_node(branch_root_id)
+    if not tree:
+        return
+
+    # 1) Cancel branch tasks (no stop_all)
+    cancelled = await handler.tree_queue.cancel_branch(branch_root_id)
+    handler.update_cancelled_nodes_ui(cancelled)
+
+    # 2) Collect message IDs from branch nodes only
+    msg_ids: set[str] = set()
+    branch_ids = tree.get_descendants(branch_root_id)
+    for nid in branch_ids:
+        node = tree.get_node(nid)
+        if node:
+            if node.incoming.message_id:
+                msg_ids.add(str(node.incoming.message_id))
+            if node.status_message_id:
+                msg_ids.add(str(node.status_message_id))
+    if incoming.message_id:
+        msg_ids.add(str(incoming.message_id))
+
+    # 3) Delete messages (best-effort)
+    await _delete_message_ids(handler, incoming.chat_id, msg_ids)
+
+    # 4) Remove branch from tree
+    removed, root_id, removed_entire_tree = await handler.tree_queue.remove_branch(
+        branch_root_id
+    )
+
+    # 5) Update session store
+    try:
+        handler.session_store.remove_node_mappings([n.node_id for n in removed])
+        if removed_entire_tree:
+            handler.session_store.remove_tree(root_id)
+        else:
+            updated_tree = handler.tree_queue.get_tree(root_id)
+            if updated_tree:
+                handler.session_store.save_tree(root_id, updated_tree.to_dict())
+    except Exception as e:
+        logger.warning(f"Failed to update session store after branch clear: {e}")
+
+
+async def handle_clear_command(
+    handler: ClaudeMessageHandler, incoming: IncomingMessage
+) -> None:
+    """
+    Handle /clear command.
+
+    Reply-scoped: reply to a message to clear that branch (node + descendants).
+    Standalone: global clear (stop all, delete all chat messages, reset store).
+    """
+    from messaging.trees import TreeQueueManager
+
+    if incoming.is_reply() and incoming.reply_to_message_id:
+        reply_id = incoming.reply_to_message_id
+        tree = handler.tree_queue.get_tree_for_node(reply_id)
+        branch_root_id = (
+            handler.tree_queue.resolve_parent_node_id(reply_id) if tree else None
+        )
+        if not branch_root_id:
+            cancel_fn = getattr(handler.platform, "cancel_pending_voice", None)
+            if cancel_fn is not None:
+                cancelled = await cancel_fn(incoming.chat_id, reply_id)
+                if cancelled is not None:
+                    voice_msg_id, status_msg_id = cancelled
+                    msg_ids_to_del: set[str] = {voice_msg_id, status_msg_id}
+                    if incoming.message_id is not None:
+                        msg_ids_to_del.add(str(incoming.message_id))
+                    await _delete_message_ids(handler, incoming.chat_id, msg_ids_to_del)
+                    msg_id = await handler.platform.queue_send_message(
+                        incoming.chat_id,
+                        handler.format_status("🗑", "Cleared.", "Voice note cancelled."),
+                        fire_and_forget=False,
+                        message_thread_id=incoming.message_thread_id,
+                    )
+                    handler.record_outgoing_message(
+                        incoming.platform, incoming.chat_id, msg_id, "command"
+                    )
+                    return
+            msg_id = await handler.platform.queue_send_message(
+                incoming.chat_id,
+                handler.format_status(
+                    "🗑", "Cleared.", "Nothing to clear for that message."
+                ),
+                fire_and_forget=False,
+                message_thread_id=incoming.message_thread_id,
+            )
+            handler.record_outgoing_message(
+                incoming.platform, incoming.chat_id, msg_id, "command"
+            )
+            return
+        await _handle_clear_branch(handler, incoming, branch_root_id)
+        return
+
+    # Global clear
+    # 1) Stop tasks first (ensures no more work is running).
+    await handler.stop_all_tasks()
+
+    # 2) Clear chat: best-effort delete messages we can identify.
+    msg_ids: set[str] = set()
+
+    # Add any recorded message IDs for this chat (commands, command replies, etc).
+    try:
+        for mid in handler.session_store.get_message_ids_for_chat(
+            incoming.platform, incoming.chat_id
+        ):
+            if mid is not None:
+                msg_ids.add(str(mid))
+    except Exception as e:
+        logger.debug(f"Failed to read message log for /clear: {e}")
+
+    try:
+        msg_ids.update(
+            handler.tree_queue.get_message_ids_for_chat(
+                incoming.platform, incoming.chat_id
+            )
+        )
+    except Exception as e:
+        logger.warning(f"Failed to gather messages for /clear: {e}")
+
+    # Also delete the command message itself.
+    if incoming.message_id is not None:
+        msg_ids.add(str(incoming.message_id))
+
+    await _delete_message_ids(handler, incoming.chat_id, msg_ids)
+
+    # 3) Clear persistent state and reset in-memory queue/tree state.
+    try:
+        handler.session_store.clear_all()
+    except Exception as e:
+        logger.warning(f"Failed to clear session store: {e}")
+
+    handler.replace_tree_queue(
+        TreeQueueManager(
+            queue_update_callback=handler.update_queue_positions,
+            node_started_callback=handler.mark_node_processing,
+        )
+    )

Claude_Code/messaging/event_parser.py

@@ -0,0 +1,163 @@
+"""CLI event parser for Claude Code CLI output.
+
+This parser emits an ordered stream of low-level events suitable for building a
+Claude Code-like transcript in messaging UIs.
+"""
+
+from typing import Any
+
+from loguru import logger
+
+
+def parse_cli_event(event: Any) -> list[dict]:
+    """
+    Parse a CLI event and return a structured result.
+
+    Args:
+        event: Raw event dictionary from CLI
+
+    Returns:
+        List of parsed event dicts. Empty list if not recognized.
+    """
+    if not isinstance(event, dict):
+        return []
+
+    etype = event.get("type")
+    results: list[dict[str, Any]] = []
+
+    # Some CLI/proxy layers emit "system" events that are not user-visible and
+    # carry no transcript content. Ignore them explicitly to avoid noisy logs.
+    if etype == "system":
+        return []
+
+    # 1. Handle full messages (assistant/user or result)
+    msg_obj = None
+    if etype == "assistant" or etype == "user":
+        msg_obj = event.get("message")
+    elif etype == "result":
+        res = event.get("result")
+        if isinstance(res, dict):
+            msg_obj = res.get("message")
+            # Some variants put content directly on the result.
+            if not msg_obj and isinstance(res.get("content"), list):
+                msg_obj = {"content": res.get("content")}
+        if not msg_obj:
+            msg_obj = event.get("message")
+        # Some variants put content directly on the event.
+        if not msg_obj and isinstance(event.get("content"), list):
+            msg_obj = {"content": event.get("content")}
+
+    if msg_obj and isinstance(msg_obj, dict):
+        content = msg_obj.get("content", [])
+        if isinstance(content, list):
+            # Preserve order exactly as content blocks appear.
+            for c in content:
+                if not isinstance(c, dict):
+                    continue
+                ctype = c.get("type")
+                if ctype == "text":
+                    results.append({"type": "text_chunk", "text": c.get("text", "")})
+                elif ctype == "thinking":
+                    results.append(
+                        {"type": "thinking_chunk", "text": c.get("thinking", "")}
+                    )
+                elif ctype == "tool_use":
+                    results.append(
+                        {
+                            "type": "tool_use",
+                            "id": str(c.get("id", "") or "").strip(),
+                            "name": c.get("name", ""),
+                            "input": c.get("input"),
+                        }
+                    )
+                elif ctype == "tool_result":
+                    results.append(
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": str(c.get("tool_use_id", "") or "").strip(),
+                            "content": c.get("content"),
+                            "is_error": bool(c.get("is_error", False)),
+                        }
+                    )
+
+        if results:
+            return results
+
+    # 2. Handle streaming deltas
+    if etype == "content_block_delta":
+        delta = event.get("delta", {})
+        if isinstance(delta, dict):
+            if delta.get("type") == "text_delta":
+                return [
+                    {
+                        "type": "text_delta",
+                        "index": event.get("index", -1),
+                        "text": delta.get("text", ""),
+                    }
+                ]
+            if delta.get("type") == "thinking_delta":
+                return [
+                    {
+                        "type": "thinking_delta",
+                        "index": event.get("index", -1),
+                        "text": delta.get("thinking", ""),
+                    }
+                ]
+            if delta.get("type") == "input_json_delta":
+                return [
+                    {
+                        "type": "tool_use_delta",
+                        "index": event.get("index", -1),
+                        "partial_json": delta.get("partial_json", ""),
+                    }
+                ]
+
+    # 3. Handle tool usage start
+    if etype == "content_block_start":
+        block = event.get("content_block", {})
+        if isinstance(block, dict):
+            btype = block.get("type")
+            if btype == "thinking":
+                return [{"type": "thinking_start", "index": event.get("index", -1)}]
+            if btype == "text":
+                return [{"type": "text_start", "index": event.get("index", -1)}]
+            if btype == "tool_use":
+                return [
+                    {
+                        "type": "tool_use_start",
+                        "index": event.get("index", -1),
+                        "id": str(block.get("id", "") or "").strip(),
+                        "name": block.get("name", ""),
+                        "input": block.get("input"),
+                    }
+                ]
+
+    # 3.5 Handle block stop (to close open streaming segments)
+    if etype == "content_block_stop":
+        return [{"type": "block_stop", "index": event.get("index", -1)}]
+
+    # 4. Handle errors and exit
+    if etype == "error":
+        err = event.get("error")
+        msg = err.get("message") if isinstance(err, dict) else str(err)
+        logger.info(f"CLI_PARSER: Parsed error event: {msg}")
+        return [{"type": "error", "message": msg}]
+    elif etype == "exit":
+        code = event.get("code", 0)
+        stderr = event.get("stderr")
+        if code == 0:
+            logger.debug(f"CLI_PARSER: Successful exit (code={code})")
+            return [{"type": "complete", "status": "success"}]
+        else:
+            # Non-zero exit is an error
+            error_msg = stderr if stderr else f"Process exited with code {code}"
+            logger.warning(f"CLI_PARSER: Error exit (code={code}): {error_msg}")
+            return [
+                {"type": "error", "message": error_msg},
+                {"type": "complete", "status": "failed"},
+            ]
+
+    # Log unrecognized events for debugging
+    if etype:
+        logger.debug(f"CLI_PARSER: Unrecognized event type: {etype}")
+    return []

Claude_Code/messaging/handler.py

@@ -0,0 +1,770 @@
+"""
+Claude Message Handler
+
+Platform-agnostic Claude interaction logic.
+Handles the core workflow of processing user messages via Claude CLI.
+Uses tree-based queuing for message ordering.
+"""
+
+import asyncio
+import os
+import time
+
+from loguru import logger
+
+from providers.common import get_user_facing_error_message
+
+from .commands import (
+    handle_clear_command,
+    handle_stats_command,
+    handle_stop_command,
+)
+from .event_parser import parse_cli_event
+from .models import IncomingMessage
+from .platforms.base import MessagingPlatform, SessionManagerInterface
+from .rendering.discord_markdown import (
+    discord_bold,
+    discord_code_inline,
+    escape_discord,
+    escape_discord_code,
+    render_markdown_to_discord,
+)
+from .rendering.discord_markdown import (
+    format_status as format_status_discord,  # (emoji, label, suffix)
+)
+from .rendering.telegram_markdown import (
+    escape_md_v2,
+    escape_md_v2_code,
+    mdv2_bold,
+    mdv2_code_inline,
+    render_markdown_to_mdv2,
+)
+from .rendering.telegram_markdown import (
+    format_status as format_status_telegram,
+)
+from .session import SessionStore
+from .transcript import RenderCtx, TranscriptBuffer
+from .trees.queue_manager import (
+    MessageNode,
+    MessageState,
+    MessageTree,
+    TreeQueueManager,
+)
+
+# Status message prefixes used to filter our own messages (ignore echo)
+STATUS_MESSAGE_PREFIXES = ("⏳", "💭", "🔧", "✅", "❌", "🚀", "🤖", "📋", "📊", "🔄")
+
+# Event types that update the transcript (frozenset for O(1) membership)
+TRANSCRIPT_EVENT_TYPES = frozenset(
+    {
+        "thinking_start",
+        "thinking_delta",
+        "thinking_chunk",
+        "thinking_stop",
+        "text_start",
+        "text_delta",
+        "text_chunk",
+        "text_stop",
+        "tool_use_start",
+        "tool_use_delta",
+        "tool_use_stop",
+        "tool_use",
+        "tool_result",
+        "block_stop",
+        "error",
+    }
+)
+
+# Event type -> (emoji, label) for status updates (O(1) lookup)
+_EVENT_STATUS_MAP = {
+    "thinking_start": ("🧠", "Claude is thinking..."),
+    "thinking_delta": ("🧠", "Claude is thinking..."),
+    "thinking_chunk": ("🧠", "Claude is thinking..."),
+    "text_start": ("🧠", "Claude is working..."),
+    "text_delta": ("🧠", "Claude is working..."),
+    "text_chunk": ("🧠", "Claude is working..."),
+    "tool_result": ("⏳", "Executing tools..."),
+}
+
+
+def _get_status_for_event(ptype: str, parsed: dict, format_status_fn) -> str | None:
+    """Return status string for event type, or None if no status update needed."""
+    entry = _EVENT_STATUS_MAP.get(ptype)
+    if entry is not None:
+        emoji, label = entry
+        return format_status_fn(emoji, label)
+    if ptype in ("tool_use_start", "tool_use_delta", "tool_use"):
+        if parsed.get("name") == "Task":
+            return format_status_fn("🤖", "Subagent working...")
+        return format_status_fn("⏳", "Executing tools...")
+    return None
+
+
+class ClaudeMessageHandler:
+    """
+    Platform-agnostic handler for Claude interactions.
+
+    Uses a tree-based message queue where:
+    - New messages create a tree root
+    - Replies become children of the message being replied to
+    - Each node has state: PENDING, IN_PROGRESS, COMPLETED, ERROR
+    - Per-tree queue ensures ordered processing
+    """
+
+    def __init__(
+        self,
+        platform: MessagingPlatform,
+        cli_manager: SessionManagerInterface,
+        session_store: SessionStore,
+    ):
+        self.platform = platform
+        self.cli_manager = cli_manager
+        self.session_store = session_store
+        self._tree_queue = TreeQueueManager(
+            queue_update_callback=self.update_queue_positions,
+            node_started_callback=self.mark_node_processing,
+        )
+        is_discord = platform.name == "discord"
+        self._format_status_fn = (
+            format_status_discord if is_discord else format_status_telegram
+        )
+        self._parse_mode_val: str | None = None if is_discord else "MarkdownV2"
+        self._render_ctx_val = RenderCtx(
+            bold=discord_bold if is_discord else mdv2_bold,
+            code_inline=discord_code_inline if is_discord else mdv2_code_inline,
+            escape_code=escape_discord_code if is_discord else escape_md_v2_code,
+            escape_text=escape_discord if is_discord else escape_md_v2,
+            render_markdown=render_markdown_to_discord
+            if is_discord
+            else render_markdown_to_mdv2,
+        )
+        self._limit_chars = 1900 if is_discord else 3900
+
+    def format_status(self, emoji: str, label: str, suffix: str | None = None) -> str:
+        return self._format_status_fn(emoji, label, suffix)
+
+    def _parse_mode(self) -> str | None:
+        return self._parse_mode_val
+
+    def get_render_ctx(self) -> RenderCtx:
+        return self._render_ctx_val
+
+    def _get_limit_chars(self) -> int:
+        return self._limit_chars
+
+    @property
+    def tree_queue(self) -> TreeQueueManager:
+        """Accessor for the current tree queue manager."""
+        return self._tree_queue
+
+    def replace_tree_queue(self, tree_queue: TreeQueueManager) -> None:
+        """Replace tree queue manager via explicit API."""
+        self._tree_queue = tree_queue
+        self._tree_queue.set_queue_update_callback(self.update_queue_positions)
+        self._tree_queue.set_node_started_callback(self.mark_node_processing)
+
+    async def handle_message(self, incoming: IncomingMessage) -> None:
+        """
+        Main entry point for handling an incoming message.
+
+        Determines if this is a new conversation or reply,
+        creates/extends the message tree, and queues for processing.
+        """
+        text_preview = (incoming.text or "")[:80]
+        if len(incoming.text or "") > 80:
+            text_preview += "..."
+        logger.info(
+            "HANDLER_ENTRY: chat_id={} message_id={} reply_to={} text_preview={!r}",
+            incoming.chat_id,
+            incoming.message_id,
+            incoming.reply_to_message_id,
+            text_preview,
+        )
+
+        with logger.contextualize(
+            chat_id=incoming.chat_id, node_id=incoming.message_id
+        ):
+            await self._handle_message_impl(incoming)
+
+    async def _handle_message_impl(self, incoming: IncomingMessage) -> None:
+        """Implementation of handle_message with context bound."""
+        # Check for commands
+        parts = (incoming.text or "").strip().split()
+        cmd = parts[0] if parts else ""
+        cmd_base = cmd.split("@", 1)[0] if cmd else ""
+
+        # Record incoming message ID for best-effort UI clearing (/clear), even if
+        # we later ignore this message (status/command/etc).
+        try:
+            if incoming.message_id is not None:
+                kind = "command" if cmd_base.startswith("/") else "content"
+                self.session_store.record_message_id(
+                    incoming.platform,
+                    incoming.chat_id,
+                    str(incoming.message_id),
+                    direction="in",
+                    kind=kind,
+                )
+        except Exception as e:
+            logger.debug(f"Failed to record incoming message_id: {e}")
+
+        if cmd_base == "/clear":
+            await self._handle_clear_command(incoming)
+            return
+
+        if cmd_base == "/stop":
+            await self._handle_stop_command(incoming)
+            return
+
+        if cmd_base == "/stats":
+            await self._handle_stats_command(incoming)
+            return
+
+        # Filter out status messages (our own messages)
+        text = incoming.text or ""
+        if any(text.startswith(p) for p in STATUS_MESSAGE_PREFIXES):
+            return
+
+        # Check if this is a reply to an existing node in a tree
+        parent_node_id = None
+        tree = None
+
+        if incoming.is_reply() and incoming.reply_to_message_id:
+            # Look up if the replied-to message is in any tree (could be a node or status message)
+            reply_id = incoming.reply_to_message_id
+            tree = self.tree_queue.get_tree_for_node(reply_id)
+            if tree:
+                # Resolve to actual node ID (handles status message replies)
+                parent_node_id = self.tree_queue.resolve_parent_node_id(reply_id)
+                if parent_node_id:
+                    logger.info(f"Found tree for reply, parent node: {parent_node_id}")
+                else:
+                    logger.warning(
+                        f"Reply to {incoming.reply_to_message_id} found tree but no valid parent node"
+                    )
+                    tree = None  # Treat as new conversation
+
+        # Generate node ID
+        node_id = incoming.message_id
+
+        # Use pre-sent status (e.g. voice note) or send new
+        status_text = self._get_initial_status(tree, parent_node_id)
+        if incoming.status_message_id:
+            status_msg_id = incoming.status_message_id
+            await self.platform.queue_edit_message(
+                incoming.chat_id,
+                status_msg_id,
+                status_text,
+                parse_mode=self._parse_mode(),
+                fire_and_forget=False,
+            )
+        else:
+            status_msg_id = await self.platform.queue_send_message(
+                incoming.chat_id,
+                status_text,
+                reply_to=incoming.message_id,
+                fire_and_forget=False,
+                message_thread_id=incoming.message_thread_id,
+            )
+        self.record_outgoing_message(
+            incoming.platform, incoming.chat_id, status_msg_id, "status"
+        )
+
+        # Create or extend tree
+        if parent_node_id and tree and status_msg_id:
+            # Reply to existing node - add as child
+            tree, _node = await self.tree_queue.add_to_tree(
+                parent_node_id=parent_node_id,
+                node_id=node_id,
+                incoming=incoming,
+                status_message_id=status_msg_id,
+            )
+            # Register status message as a node too for reply chains
+            self.tree_queue.register_node(status_msg_id, tree.root_id)
+            self.session_store.register_node(status_msg_id, tree.root_id)
+            self.session_store.register_node(node_id, tree.root_id)
+        elif status_msg_id:
+            # New conversation - create new tree
+            tree = await self.tree_queue.create_tree(
+                node_id=node_id,
+                incoming=incoming,
+                status_message_id=status_msg_id,
+            )
+            # Register status message
+            self.tree_queue.register_node(status_msg_id, tree.root_id)
+            self.session_store.register_node(node_id, tree.root_id)
+            self.session_store.register_node(status_msg_id, tree.root_id)
+
+        # Persist tree
+        if tree:
+            self.session_store.save_tree(tree.root_id, tree.to_dict())
+
+        # Enqueue for processing
+        was_queued = await self.tree_queue.enqueue(
+            node_id=node_id,
+            processor=self._process_node,
+        )
+
+        if was_queued and status_msg_id:
+            # Update status to show queue position
+            queue_size = self.tree_queue.get_queue_size(node_id)
+            await self.platform.queue_edit_message(
+                incoming.chat_id,
+                status_msg_id,
+                self.format_status(
+                    "📋", "Queued", f"(position {queue_size}) - waiting..."
+                ),
+                parse_mode=self._parse_mode(),
+            )
+
+    async def update_queue_positions(self, tree: MessageTree) -> None:
+        """Refresh queued status messages after a dequeue."""
+        try:
+            queued_ids = await tree.get_queue_snapshot()
+        except Exception as e:
+            logger.warning(f"Failed to read queue snapshot: {e}")
+            return
+
+        if not queued_ids:
+            return
+
+        position = 0
+        for node_id in queued_ids:
+            node = tree.get_node(node_id)
+            if not node or node.state != MessageState.PENDING:
+                continue
+            position += 1
+            self.platform.fire_and_forget(
+                self.platform.queue_edit_message(
+                    node.incoming.chat_id,
+                    node.status_message_id,
+                    self.format_status(
+                        "📋", "Queued", f"(position {position}) - waiting..."
+                    ),
+                    parse_mode=self._parse_mode(),
+                )
+            )
+
+    async def mark_node_processing(self, tree: MessageTree, node_id: str) -> None:
+        """Update the dequeued node's status to processing immediately."""
+        node = tree.get_node(node_id)
+        if not node or node.state == MessageState.ERROR:
+            return
+        self.platform.fire_and_forget(
+            self.platform.queue_edit_message(
+                node.incoming.chat_id,
+                node.status_message_id,
+                self.format_status("🔄", "Processing..."),
+                parse_mode=self._parse_mode(),
+            )
+        )
+
+    def _create_transcript_and_render_ctx(
+        self,
+    ) -> tuple[TranscriptBuffer, RenderCtx]:
+        """Create transcript buffer and render context for node processing."""
+        transcript = TranscriptBuffer(show_tool_results=False)
+        return transcript, self.get_render_ctx()
+
+    async def _handle_session_info_event(
+        self,
+        event_data: dict,
+        tree: MessageTree | None,
+        node_id: str,
+        captured_session_id: str | None,
+        temp_session_id: str | None,
+    ) -> tuple[str | None, str | None]:
+        """Handle session_info event; return updated (captured_session_id, temp_session_id)."""
+        if event_data.get("type") != "session_info":
+            return captured_session_id, temp_session_id
+
+        real_session_id = event_data.get("session_id")
+        if not real_session_id or not temp_session_id:
+            return captured_session_id, temp_session_id
+
+        await self.cli_manager.register_real_session_id(
+            temp_session_id, real_session_id
+        )
+        if tree and real_session_id:
+            await tree.update_state(
+                node_id,
+                MessageState.IN_PROGRESS,
+                session_id=real_session_id,
+            )
+            self.session_store.save_tree(tree.root_id, tree.to_dict())
+
+        return real_session_id, None
+
+    async def _process_parsed_event(
+        self,
+        parsed: dict,
+        transcript: TranscriptBuffer,
+        update_ui,
+        last_status: str | None,
+        had_transcript_events: bool,
+        tree: MessageTree | None,
+        node_id: str,
+        captured_session_id: str | None,
+    ) -> tuple[str | None, bool]:
+        """Process a single parsed CLI event. Returns (last_status, had_transcript_events)."""
+        ptype = parsed.get("type") or ""
+
+        if ptype in TRANSCRIPT_EVENT_TYPES:
+            transcript.apply(parsed)
+            had_transcript_events = True
+
+        status = _get_status_for_event(ptype, parsed, self.format_status)
+        if status is not None:
+            await update_ui(status)
+            last_status = status
+        elif ptype == "block_stop":
+            await update_ui(last_status, force=True)
+        elif ptype == "complete":
+            if not had_transcript_events:
+                transcript.apply({"type": "text_chunk", "text": "Done."})
+            logger.info("HANDLER: Task complete, updating UI")
+            await update_ui(self.format_status("✅", "Complete"), force=True)
+            if tree and captured_session_id:
+                await tree.update_state(
+                    node_id,
+                    MessageState.COMPLETED,
+                    session_id=captured_session_id,
+                )
+                self.session_store.save_tree(tree.root_id, tree.to_dict())
+        elif ptype == "error":
+            error_msg = parsed.get("message", "Unknown error")
+            logger.error(f"HANDLER: Error event received: {error_msg}")
+            logger.info("HANDLER: Updating UI with error status")
+            await update_ui(self.format_status("❌", "Error"), force=True)
+            if tree:
+                await self._propagate_error_to_children(
+                    node_id, error_msg, "Parent task failed"
+                )
+
+        return last_status, had_transcript_events
+
+    async def _process_node(
+        self,
+        node_id: str,
+        node: MessageNode,
+    ) -> None:
+        """Core task processor - handles a single Claude CLI interaction."""
+        incoming = node.incoming
+        status_msg_id = node.status_message_id
+        chat_id = incoming.chat_id
+
+        with logger.contextualize(node_id=node_id, chat_id=chat_id):
+            await self._process_node_impl(node_id, node, chat_id, status_msg_id)
+
+    async def _process_node_impl(
+        self,
+        node_id: str,
+        node: MessageNode,
+        chat_id: str,
+        status_msg_id: str,
+    ) -> None:
+        """Internal implementation of _process_node with context bound."""
+        incoming = node.incoming
+
+        tree = self.tree_queue.get_tree_for_node(node_id)
+        if tree:
+            await tree.update_state(node_id, MessageState.IN_PROGRESS)
+
+        transcript, render_ctx = self._create_transcript_and_render_ctx()
+
+        last_ui_update = 0.0
+        last_displayed_text = None
+        had_transcript_events = False
+        captured_session_id = None
+        temp_session_id = None
+        last_status: str | None = None
+
+        parent_session_id = None
+        if tree and node.parent_id:
+            parent_session_id = tree.get_parent_session_id(node_id)
+            if parent_session_id:
+                logger.info(f"Will fork from parent session: {parent_session_id}")
+
+        async def update_ui(status: str | None = None, force: bool = False) -> None:
+            nonlocal last_ui_update, last_displayed_text, last_status
+            now = time.time()
+            if not force and now - last_ui_update < 1.0:
+                return
+
+            last_ui_update = now
+            if status is not None:
+                last_status = status
+            try:
+                display = transcript.render(
+                    render_ctx,
+                    limit_chars=self._get_limit_chars(),
+                    status=status,
+                )
+            except Exception as e:
+                logger.warning(f"Transcript render failed for node {node_id}: {e}")
+                return
+            if display and display != last_displayed_text:
+                logger.debug(
+                    "PLATFORM_EDIT: node_id={} chat_id={} msg_id={} force={} status={!r} chars={}",
+                    node_id,
+                    chat_id,
+                    status_msg_id,
+                    bool(force),
+                    status,
+                    len(display),
+                )
+                if os.getenv("DEBUG_TELEGRAM_EDITS") == "1":
+                    logger.debug("PLATFORM_EDIT_TEXT:\n{}", display)
+                else:
+                    head = display[:500]
+                    tail = display[-500:] if len(display) > 500 else ""
+                    logger.debug("PLATFORM_EDIT_PREVIEW_HEAD:\n{}", head)
+                    if tail:
+                        logger.debug("PLATFORM_EDIT_PREVIEW_TAIL:\n{}", tail)
+                last_displayed_text = display
+                try:
+                    await self.platform.queue_edit_message(
+                        chat_id,
+                        status_msg_id,
+                        display,
+                        parse_mode=self._parse_mode(),
+                    )
+                except Exception as e:
+                    logger.warning(f"Failed to update platform for node {node_id}: {e}")
+
+        try:
+            try:
+                (
+                    cli_session,
+                    session_or_temp_id,
+                    is_new,
+                ) = await self.cli_manager.get_or_create_session(session_id=None)
+                if is_new:
+                    temp_session_id = session_or_temp_id
+                else:
+                    captured_session_id = session_or_temp_id
+            except RuntimeError as e:
+                error_message = get_user_facing_error_message(e)
+                transcript.apply({"type": "error", "message": error_message})
+                await update_ui(
+                    self.format_status("⏳", "Session limit reached"),
+                    force=True,
+                )
+                if tree:
+                    await tree.update_state(
+                        node_id,
+                        MessageState.ERROR,
+                        error_message=error_message,
+                    )
+                return
+
+            logger.info(f"HANDLER: Starting CLI task processing for node {node_id}")
+            event_count = 0
+            async for event_data in cli_session.start_task(
+                incoming.text,
+                session_id=parent_session_id,
+                fork_session=bool(parent_session_id),
+            ):
+                if not isinstance(event_data, dict):
+                    logger.warning(
+                        f"HANDLER: Non-dict event received: {type(event_data)}"
+                    )
+                    continue
+                event_count += 1
+                if event_count % 10 == 0:
+                    logger.debug(f"HANDLER: Processed {event_count} events so far")
+
+                (
+                    captured_session_id,
+                    temp_session_id,
+                ) = await self._handle_session_info_event(
+                    event_data, tree, node_id, captured_session_id, temp_session_id
+                )
+                if event_data.get("type") == "session_info":
+                    continue
+
+                parsed_list = parse_cli_event(event_data)
+                logger.debug(f"HANDLER: Parsed {len(parsed_list)} events from CLI")
+
+                for parsed in parsed_list:
+                    (
+                        last_status,
+                        had_transcript_events,
+                    ) = await self._process_parsed_event(
+                        parsed,
+                        transcript,
+                        update_ui,
+                        last_status,
+                        had_transcript_events,
+                        tree,
+                        node_id,
+                        captured_session_id,
+                    )
+
+        except asyncio.CancelledError:
+            logger.warning(f"HANDLER: Task cancelled for node {node_id}")
+            cancel_reason = None
+            if isinstance(node.context, dict):
+                cancel_reason = node.context.get("cancel_reason")
+
+            if cancel_reason == "stop":
+                await update_ui(self.format_status("⏹", "Stopped."), force=True)
+            else:
+                transcript.apply({"type": "error", "message": "Task was cancelled"})
+                await update_ui(self.format_status("❌", "Cancelled"), force=True)
+
+            # Do not propagate cancellation to children; a reply-scoped "/stop"
+            # should only stop the targeted task.
+            if tree:
+                await tree.update_state(
+                    node_id, MessageState.ERROR, error_message="Cancelled by user"
+                )
+        except Exception as e:
+            logger.error(
+                f"HANDLER: Task failed with exception: {type(e).__name__}: {e}"
+            )
+            error_msg = get_user_facing_error_message(e)[:200]
+            transcript.apply({"type": "error", "message": error_msg})
+            await update_ui(self.format_status("💥", "Task Failed"), force=True)
+            if tree:
+                await self._propagate_error_to_children(
+                    node_id, error_msg, "Parent task failed"
+                )
+        finally:
+            logger.info(f"HANDLER: _process_node completed for node {node_id}")
+            # Free the session-manager slot. Session IDs are persisted in the tree and
+            # can be resumed later by ID; we don't need to keep a CLISession instance
+            # around after this node completes.
+            try:
+                if captured_session_id:
+                    await self.cli_manager.remove_session(captured_session_id)
+                elif temp_session_id:
+                    await self.cli_manager.remove_session(temp_session_id)
+            except Exception as e:
+                logger.debug(f"Failed to remove session for node {node_id}: {e}")
+
+    async def _propagate_error_to_children(
+        self,
+        node_id: str,
+        error_msg: str,
+        child_status_text: str,
+    ) -> None:
+        """Mark node as error and propagate to pending children with UI updates."""
+        affected = await self.tree_queue.mark_node_error(
+            node_id, error_msg, propagate_to_children=True
+        )
+        # Update status messages for all affected children (skip first = current node)
+        for child in affected[1:]:
+            self.platform.fire_and_forget(
+                self.platform.queue_edit_message(
+                    child.incoming.chat_id,
+                    child.status_message_id,
+                    self.format_status("❌", "Cancelled:", child_status_text),
+                    parse_mode=self._parse_mode(),
+                )
+            )
+
+    def _get_initial_status(
+        self,
+        tree: object | None,
+        parent_node_id: str | None,
+    ) -> str:
+        """Get initial status message text."""
+        if tree and parent_node_id:
+            # Reply to existing tree
+            if self.tree_queue.is_node_tree_busy(parent_node_id):
+                queue_size = self.tree_queue.get_queue_size(parent_node_id) + 1
+                return self.format_status(
+                    "📋", "Queued", f"(position {queue_size}) - waiting..."
+                )
+            return self.format_status("🔄", "Continuing conversation...")
+
+        # New conversation
+        return self.format_status("⏳", "Launching new Claude CLI instance...")
+
+    async def stop_all_tasks(self) -> int:
+        """
+        Stop all pending and in-progress tasks.
+
+        Order of operations:
+        1. Cancel tree queue tasks (uses internal locking)
+        2. Stop CLI sessions
+        3. Update UI for all affected nodes
+        """
+        # 1. Cancel tree queue tasks using the public async method
+        logger.info("Cancelling tree queue tasks...")
+        cancelled_nodes = await self.tree_queue.cancel_all()
+        logger.info(f"Cancelled {len(cancelled_nodes)} nodes")
+
+        # 2. Stop CLI sessions - this kills subprocesses and ensures everything is dead
+        logger.info("Stopping all CLI sessions...")
+        await self.cli_manager.stop_all()
+
+        # 3. Update UI and persist state for all cancelled nodes
+        self.update_cancelled_nodes_ui(cancelled_nodes)
+
+        return len(cancelled_nodes)
+
+    async def stop_task(self, node_id: str) -> int:
+        """
+        Stop a single queued or in-progress task node.
+
+        Used when the user replies "/stop" to a specific status/user message.
+        """
+        tree = self.tree_queue.get_tree_for_node(node_id)
+        if tree:
+            node = tree.get_node(node_id)
+            if node and node.state not in (MessageState.COMPLETED, MessageState.ERROR):
+                # Used by _process_node cancellation path to render "Stopped."
+                node.set_context({"cancel_reason": "stop"})
+
+        cancelled_nodes = await self.tree_queue.cancel_node(node_id)
+        self.update_cancelled_nodes_ui(cancelled_nodes)
+        return len(cancelled_nodes)
+
+    def record_outgoing_message(
+        self,
+        platform: str,
+        chat_id: str,
+        msg_id: str | None,
+        kind: str,
+    ) -> None:
+        """Record outgoing message ID for /clear. Best-effort, never raises."""
+        if not msg_id:
+            return
+        try:
+            self.session_store.record_message_id(
+                platform, chat_id, str(msg_id), direction="out", kind=kind
+            )
+        except Exception as e:
+            logger.debug(f"Failed to record message_id: {e}")
+
+    def update_cancelled_nodes_ui(self, nodes: list[MessageNode]) -> None:
+        """Update status messages and persist tree state for cancelled nodes."""
+        trees_to_save: dict[str, MessageTree] = {}
+        for node in nodes:
+            self.platform.fire_and_forget(
+                self.platform.queue_edit_message(
+                    node.incoming.chat_id,
+                    node.status_message_id,
+                    self.format_status("⏹", "Stopped."),
+                    parse_mode=self._parse_mode(),
+                )
+            )
+            tree = self.tree_queue.get_tree_for_node(node.node_id)
+            if tree:
+                trees_to_save[tree.root_id] = tree
+        for root_id, tree in trees_to_save.items():
+            self.session_store.save_tree(root_id, tree.to_dict())
+
+    async def _handle_stop_command(self, incoming: IncomingMessage) -> None:
+        """Handle /stop command from messaging platform."""
+        await handle_stop_command(self, incoming)
+
+    async def _handle_stats_command(self, incoming: IncomingMessage) -> None:
+        """Handle /stats command."""
+        await handle_stats_command(self, incoming)
+
+    async def _handle_clear_command(self, incoming: IncomingMessage) -> None:
+        """Handle /clear command."""
+        await handle_clear_command(self, incoming)

Claude_Code/messaging/limiter.py

@@ -0,0 +1,312 @@
+"""
+Global Rate Limiter for Messaging Platforms.
+
+Centralizes outgoing message requests and ensures compliance with rate limits
+using a strict sliding window algorithm and a task queue.
+"""
+
+import asyncio
+import os
+import time
+from collections import deque
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from loguru import logger
+
+
+class SlidingWindowLimiter:
+    """Strict sliding window limiter.
+
+    Guarantees: at most `rate_limit` acquisitions in any interval of length
+    `rate_window` (seconds).
+
+    Implemented as an async context manager so call sites can do:
+        async with limiter:
+            ...
+    """
+
+    def __init__(self, rate_limit: int, rate_window: float) -> None:
+        if rate_limit <= 0:
+            raise ValueError("rate_limit must be > 0")
+        if rate_window <= 0:
+            raise ValueError("rate_window must be > 0")
+
+        self._rate_limit = int(rate_limit)
+        self._rate_window = float(rate_window)
+        self._times: deque[float] = deque()
+        self._lock = asyncio.Lock()
+
+    async def acquire(self) -> None:
+        while True:
+            wait_time = 0.0
+            async with self._lock:
+                now = time.monotonic()
+                cutoff = now - self._rate_window
+
+                while self._times and self._times[0] <= cutoff:
+                    self._times.popleft()
+
+                if len(self._times) < self._rate_limit:
+                    self._times.append(now)
+                    return
+
+                oldest = self._times[0]
+                wait_time = max(0.0, (oldest + self._rate_window) - now)
+
+            if wait_time > 0:
+                await asyncio.sleep(wait_time)
+            else:
+                await asyncio.sleep(0)
+
+    async def __aenter__(self) -> SlidingWindowLimiter:
+        await self.acquire()
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> bool:
+        return False
+
+
+class MessagingRateLimiter:
+    """
+    A thread-safe global rate limiter for messaging.
+
+    Uses a custom queue with task compaction (deduplication) to ensure
+    only the latest version of a message update is processed.
+    """
+
+    _instance: MessagingRateLimiter | None = None
+    _lock = asyncio.Lock()
+
+    def __new__(cls, *args, **kwargs):
+        return super().__new__(cls)
+
+    @classmethod
+    async def get_instance(cls) -> MessagingRateLimiter:
+        """Get the singleton instance of the limiter."""
+        async with cls._lock:
+            if cls._instance is None:
+                cls._instance = cls()
+                # Start the background worker (tracked for graceful shutdown).
+                cls._instance._start_worker()
+        return cls._instance
+
+    def __init__(self):
+        # Prevent double initialization in singleton
+        if hasattr(self, "_initialized"):
+            return
+
+        rate_limit = int(os.getenv("MESSAGING_RATE_LIMIT", "1"))
+        rate_window = float(os.getenv("MESSAGING_RATE_WINDOW", "2.0"))
+
+        self.limiter = SlidingWindowLimiter(rate_limit, rate_window)
+        # Custom queue state - using deque for O(1) popleft
+        self._queue_list: deque[str] = deque()  # Deque of dedup_keys in order
+        self._queue_map: dict[
+            str, tuple[Callable[[], Awaitable[Any]], list[asyncio.Future]]
+        ] = {}
+        self._condition = asyncio.Condition()
+        self._shutdown = asyncio.Event()
+        self._worker_task: asyncio.Task | None = None
+
+        self._initialized = True
+        self._paused_until = 0
+
+        logger.info(
+            f"MessagingRateLimiter initialized ({rate_limit} req / {rate_window}s with Task Compaction)"
+        )
+
+    def _start_worker(self) -> None:
+        """Ensure the worker task exists."""
+        if self._worker_task and not self._worker_task.done():
+            return
+        # Named task helps debugging shutdown hangs.
+        self._worker_task = asyncio.create_task(
+            self._worker(), name="msg-limiter-worker"
+        )
+
+    async def _worker(self):
+        """Background worker that processes queued messaging tasks."""
+        logger.info("MessagingRateLimiter worker started")
+        while not self._shutdown.is_set():
+            try:
+                # Get a task from the queue
+                async with self._condition:
+                    while not self._queue_list and not self._shutdown.is_set():
+                        await self._condition.wait()
+
+                    if self._shutdown.is_set():
+                        break
+
+                    dedup_key = self._queue_list.popleft()
+                    func, futures = self._queue_map.pop(dedup_key)
+
+                # Check for manual pause (FloodWait)
+                now = asyncio.get_event_loop().time()
+                if self._paused_until > now:
+                    wait_time = self._paused_until - now
+                    logger.warning(
+                        f"Limiter worker paused, waiting {wait_time:.1f}s more..."
+                    )
+                    await asyncio.sleep(wait_time)
+
+                # Wait for rate limit capacity
+                async with self.limiter:
+                    try:
+                        result = await func()
+                        for f in futures:
+                            if not f.done():
+                                f.set_result(result)
+                    except Exception as e:
+                        # Report error to all futures and log it
+                        for f in futures:
+                            if not f.done():
+                                f.set_exception(e)
+
+                        error_msg = str(e).lower()
+                        if "flood" in error_msg or "wait" in error_msg:
+                            seconds = 30
+                            try:
+                                if hasattr(e, "seconds"):
+                                    seconds = e.seconds
+                                elif "after " in error_msg:
+                                    # Try to parse "retry after X"
+                                    parts = error_msg.split("after ")
+                                    if len(parts) > 1:
+                                        seconds = int(parts[1].split()[0])
+                            except Exception:
+                                pass
+
+                            logger.error(
+                                f"FloodWait detected! Pausing worker for {seconds}s"
+                            )
+                            wait_secs = (
+                                float(seconds)
+                                if isinstance(seconds, (int, float, str))
+                                else 30.0
+                            )
+                            self._paused_until = (
+                                asyncio.get_event_loop().time() + wait_secs
+                            )
+                        else:
+                            logger.error(
+                                f"Error in limiter worker for key {dedup_key}: {type(e).__name__}: {e}"
+                            )
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(
+                    f"MessagingRateLimiter worker critical error: {e}", exc_info=True
+                )
+                await asyncio.sleep(1)
+
+    async def shutdown(self, timeout: float = 2.0) -> None:
+        """Stop the background worker so process shutdown doesn't hang."""
+        self._shutdown.set()
+        try:
+            async with self._condition:
+                self._condition.notify_all()
+        except Exception:
+            # Best-effort: condition may be bound to a closing loop.
+            pass
+
+        task = self._worker_task
+        if not task or task.done():
+            self._worker_task = None
+            return
+
+        task.cancel()
+        try:
+            await asyncio.wait_for(task, timeout=timeout)
+        except TimeoutError:
+            logger.warning("MessagingRateLimiter worker did not stop before timeout")
+        except asyncio.CancelledError:
+            pass
+        except Exception as e:
+            logger.debug(f"MessagingRateLimiter worker shutdown error: {e}")
+        finally:
+            self._worker_task = None
+
+    @classmethod
+    async def shutdown_instance(cls, timeout: float = 2.0) -> None:
+        """Shutdown and clear the singleton instance (safe to call multiple times)."""
+        inst = cls._instance
+        if not inst:
+            return
+        try:
+            await inst.shutdown(timeout=timeout)
+        finally:
+            cls._instance = None
+
+    async def _enqueue_internal(self, func, future, dedup_key, front=False):
+        await self._enqueue_internal_multi(func, [future], dedup_key, front)
+
+    async def _enqueue_internal_multi(self, func, futures, dedup_key, front=False):
+        async with self._condition:
+            if dedup_key in self._queue_map:
+                # Compaction: Update existing task with new func, append new futures
+                _old_func, old_futures = self._queue_map[dedup_key]
+                old_futures.extend(futures)
+                self._queue_map[dedup_key] = (func, old_futures)
+                logger.debug(
+                    f"Compacted task for key: {dedup_key} (now {len(old_futures)} futures)"
+                )
+            else:
+                self._queue_map[dedup_key] = (func, futures)
+                if front:
+                    self._queue_list.appendleft(dedup_key)
+                else:
+                    self._queue_list.append(dedup_key)
+                self._condition.notify_all()
+
+    async def enqueue(
+        self, func: Callable[[], Awaitable[Any]], dedup_key: str | None = None
+    ) -> Any:
+        """
+        Enqueue a messaging task and return its future result.
+        If dedup_key is provided, subsequent tasks with the same key will replace this one.
+        """
+        if dedup_key is None:
+            # Unique key to avoid deduplication
+            dedup_key = f"task_{id(func)}_{asyncio.get_event_loop().time()}"
+
+        future = asyncio.get_event_loop().create_future()
+        await self._enqueue_internal(func, future, dedup_key)
+        return await future
+
+    def fire_and_forget(
+        self, func: Callable[[], Awaitable[Any]], dedup_key: str | None = None
+    ):
+        """Enqueue a task without waiting for the result."""
+        if dedup_key is None:
+            dedup_key = f"task_{id(func)}_{asyncio.get_event_loop().time()}"
+
+        future = asyncio.get_event_loop().create_future()
+
+        async def _wrapped():
+            max_retries = 2
+            for attempt in range(max_retries + 1):
+                try:
+                    return await self.enqueue(func, dedup_key)
+                except Exception as e:
+                    error_msg = str(e).lower()
+                    # Only retry transient connectivity issues that might have slipped through
+                    # or occurred between platform checks.
+                    if attempt < max_retries and any(
+                        x in error_msg for x in ["connect", "timeout", "broken"]
+                    ):
+                        wait = 2**attempt
+                        logger.warning(
+                            f"Limiter fire_and_forget transient error (attempt {attempt + 1}): {e}. Retrying in {wait}s..."
+                        )
+                        await asyncio.sleep(wait)
+                        continue
+
+                    logger.error(
+                        f"Final error in fire_and_forget for key {dedup_key}: {type(e).__name__}: {e}"
+                    )
+                    if not future.done():
+                        future.set_exception(e)
+                    break
+
+        _ = asyncio.create_task(_wrapped())

Claude_Code/messaging/models.py

@@ -0,0 +1,36 @@
+"""Platform-agnostic message models."""
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+
+@dataclass
+class IncomingMessage:
+    """
+    Platform-agnostic incoming message.
+
+    Adapters convert platform-specific events to this format.
+    """
+
+    text: str
+    chat_id: str
+    user_id: str
+    message_id: str
+    platform: str  # "telegram", "discord", "slack", etc.
+
+    # Optional fields
+    reply_to_message_id: str | None = None
+    # Forum topic ID (Telegram); required when replying in forum supergroups
+    message_thread_id: str | None = None
+    username: str | None = None
+    # Pre-sent status message ID (e.g. "Transcribing voice note..."); handler edits in place
+    status_message_id: str | None = None
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+
+    # Platform-specific raw event for edge cases
+    raw_event: Any = None
+
+    def is_reply(self) -> bool:
+        """Check if this message is a reply to another message."""
+        return self.reply_to_message_id is not None

Claude_Code/messaging/platforms/__init__.py

@@ -0,0 +1,11 @@
+"""Messaging platform adapters (Telegram, Discord, etc.)."""
+
+from .base import CLISession, MessagingPlatform, SessionManagerInterface
+from .factory import create_messaging_platform
+
+__all__ = [
+    "CLISession",
+    "MessagingPlatform",
+    "SessionManagerInterface",
+    "create_messaging_platform",
+]

Claude_Code/messaging/platforms/base.py

@@ -0,0 +1,218 @@
+"""Abstract base class for messaging platforms."""
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncGenerator, Awaitable, Callable
+from typing import (
+    Any,
+    Protocol,
+    runtime_checkable,
+)
+
+from ..models import IncomingMessage
+
+
+@runtime_checkable
+class CLISession(Protocol):
+    """Protocol for CLI session - avoid circular import from cli package."""
+
+    def start_task(
+        self, prompt: str, session_id: str | None = None, fork_session: bool = False
+    ) -> AsyncGenerator[dict, Any]:
+        """Start a task in the CLI session."""
+        ...
+
+    @property
+    @abstractmethod
+    def is_busy(self) -> bool:
+        """Check if session is busy."""
+        pass
+
+
+@runtime_checkable
+class SessionManagerInterface(Protocol):
+    """
+    Protocol for session managers to avoid tight coupling with cli package.
+
+    Implementations: CLISessionManager
+    """
+
+    async def get_or_create_session(
+        self, session_id: str | None = None
+    ) -> tuple[CLISession, str, bool]:
+        """
+        Get an existing session or create a new one.
+
+        Returns: Tuple of (session, session_id, is_new_session)
+        """
+        ...
+
+    async def register_real_session_id(
+        self, temp_id: str, real_session_id: str
+    ) -> bool:
+        """Register the real session ID from CLI output."""
+        ...
+
+    async def stop_all(self) -> None:
+        """Stop all sessions."""
+        ...
+
+    async def remove_session(self, session_id: str) -> bool:
+        """Remove a session from the manager."""
+        ...
+
+    def get_stats(self) -> dict:
+        """Get session statistics."""
+        ...
+
+
+class MessagingPlatform(ABC):
+    """
+    Base class for all messaging platform adapters.
+
+    Implement this to add support for Telegram, Discord, Slack, etc.
+    """
+
+    name: str = "base"
+
+    @abstractmethod
+    async def start(self) -> None:
+        """Initialize and connect to the messaging platform."""
+        pass
+
+    @abstractmethod
+    async def stop(self) -> None:
+        """Disconnect and cleanup resources."""
+        pass
+
+    @abstractmethod
+    async def send_message(
+        self,
+        chat_id: str,
+        text: str,
+        reply_to: str | None = None,
+        parse_mode: str | None = None,
+        message_thread_id: str | None = None,
+    ) -> str:
+        """
+        Send a message to a chat.
+
+        Args:
+            chat_id: The chat/channel ID to send to
+            text: Message content
+            reply_to: Optional message ID to reply to
+            parse_mode: Optional formatting mode ("markdown", "html")
+            message_thread_id: Optional forum topic ID (Telegram)
+
+        Returns:
+            The message ID of the sent message
+        """
+        pass
+
+    @abstractmethod
+    async def edit_message(
+        self,
+        chat_id: str,
+        message_id: str,
+        text: str,
+        parse_mode: str | None = None,
+    ) -> None:
+        """
+        Edit an existing message.
+
+        Args:
+            chat_id: The chat/channel ID
+            message_id: The message ID to edit
+            text: New message content
+            parse_mode: Optional formatting mode
+        """
+        pass
+
+    @abstractmethod
+    async def delete_message(
+        self,
+        chat_id: str,
+        message_id: str,
+    ) -> None:
+        """
+        Delete a message from a chat.
+
+        Args:
+            chat_id: The chat/channel ID
+            message_id: The message ID to delete
+        """
+        pass
+
+    @abstractmethod
+    async def queue_send_message(
+        self,
+        chat_id: str,
+        text: str,
+        reply_to: str | None = None,
+        parse_mode: str | None = None,
+        fire_and_forget: bool = True,
+        message_thread_id: str | None = None,
+    ) -> str | None:
+        """
+        Enqueue a message to be sent.
+
+        If fire_and_forget is True, returns None immediately.
+        Otherwise, waits for the rate limiter and returns message ID.
+        """
+        pass
+
+    @abstractmethod
+    async def queue_edit_message(
+        self,
+        chat_id: str,
+        message_id: str,
+        text: str,
+        parse_mode: str | None = None,
+        fire_and_forget: bool = True,
+    ) -> None:
+        """
+        Enqueue a message edit.
+
+        If fire_and_forget is True, returns immediately.
+        Otherwise, waits for the rate limiter.
+        """
+        pass
+
+    @abstractmethod
+    async def queue_delete_message(
+        self,
+        chat_id: str,
+        message_id: str,
+        fire_and_forget: bool = True,
+    ) -> None:
+        """
+        Enqueue a message deletion.
+
+        If fire_and_forget is True, returns immediately.
+        Otherwise, waits for the rate limiter.
+        """
+        pass
+
+    @abstractmethod
+    def on_message(
+        self,
+        handler: Callable[[IncomingMessage], Awaitable[None]],
+    ) -> None:
+        """
+        Register a message handler callback.
+
+        The handler will be called for each incoming message.
+
+        Args:
+            handler: Async function that processes incoming messages
+        """
+        pass
+
+    @abstractmethod
+    def fire_and_forget(self, task: Awaitable[Any]) -> None:
+        """Execute a coroutine without awaiting it."""
+        pass
+
+    @property
+    def is_connected(self) -> bool:
+        """Check if the platform is connected."""
+        return False

Claude_Code/messaging/platforms/discord.py

@@ -0,0 +1,561 @@
+"""
+Discord Platform Adapter
+
+Implements MessagingPlatform for Discord using discord.py.
+"""
+
+import asyncio
+import contextlib
+import os
+import tempfile
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+from typing import Any, cast
+
+from loguru import logger
+
+from providers.common import get_user_facing_error_message
+
+from ..models import IncomingMessage
+from ..rendering.discord_markdown import format_status_discord
+from .base import MessagingPlatform
+
+AUDIO_EXTENSIONS = (".ogg", ".mp4", ".mp3", ".wav", ".m4a")
+
+_discord_module: Any = None
+try:
+    import discord as _discord_import
+
+    _discord_module = _discord_import
+    DISCORD_AVAILABLE = True
+except ImportError:
+    DISCORD_AVAILABLE = False
+
+DISCORD_MESSAGE_LIMIT = 2000
+
+
+def _get_discord() -> Any:
+    """Return the discord module. Raises if not available."""
+    if not DISCORD_AVAILABLE or _discord_module is None:
+        raise ImportError(
+            "discord.py is required. Install with: pip install discord.py"
+        )
+    return _discord_module
+
+
+def _parse_allowed_channels(raw: str | None) -> set[str]:
+    """Parse comma-separated channel IDs into a set of strings."""
+    if not raw or not raw.strip():
+        return set()
+    return {s.strip() for s in raw.split(",") if s.strip()}
+
+
+if DISCORD_AVAILABLE and _discord_module is not None:
+    _discord = _discord_module
+
+    class _DiscordClient(_discord.Client):
+        """Internal Discord client that forwards events to DiscordPlatform."""
+
+        def __init__(
+            self,
+            platform: DiscordPlatform,
+            intents: _discord.Intents,
+        ) -> None:
+            super().__init__(intents=intents)
+            self._platform = platform
+
+        async def on_ready(self) -> None:
+            """Called when the bot is ready."""
+            self._platform._connected = True
+            logger.info("Discord platform connected")
+
+        async def on_message(self, message: Any) -> None:
+            """Handle incoming Discord messages."""
+            await self._platform._handle_client_message(message)
+else:
+    _DiscordClient = None
+
+
+class DiscordPlatform(MessagingPlatform):
+    """
+    Discord messaging platform adapter.
+
+    Uses discord.py for Discord access.
+    Requires a Bot Token from Discord Developer Portal and message_content intent.
+    """
+
+    name = "discord"
+
+    def __init__(
+        self,
+        bot_token: str | None = None,
+        allowed_channel_ids: str | None = None,
+    ):
+        if not DISCORD_AVAILABLE:
+            raise ImportError(
+                "discord.py is required. Install with: pip install discord.py"
+            )
+
+        self.bot_token = bot_token or os.getenv("DISCORD_BOT_TOKEN")
+        raw_channels = allowed_channel_ids or os.getenv("ALLOWED_DISCORD_CHANNELS")
+        self.allowed_channel_ids = _parse_allowed_channels(raw_channels)
+
+        if not self.bot_token:
+            logger.warning("DISCORD_BOT_TOKEN not set")
+
+        discord = _get_discord()
+        intents = discord.Intents.default()
+        intents.message_content = True
+
+        assert _DiscordClient is not None
+        self._client = _DiscordClient(self, intents)
+        self._message_handler: Callable[[IncomingMessage], Awaitable[None]] | None = (
+            None
+        )
+        self._connected = False
+        self._limiter: Any | None = None
+        self._start_task: asyncio.Task | None = None
+        self._pending_voice: dict[tuple[str, str], tuple[str, str]] = {}
+        self._pending_voice_lock = asyncio.Lock()
+
+    async def _handle_client_message(self, message: Any) -> None:
+        """Adapter entry point used by the internal discord client."""
+        await self._on_discord_message(message)
+
+    async def _register_pending_voice(
+        self, chat_id: str, voice_msg_id: str, status_msg_id: str
+    ) -> None:
+        """Register a voice note as pending transcription."""
+        async with self._pending_voice_lock:
+            self._pending_voice[(chat_id, voice_msg_id)] = (voice_msg_id, status_msg_id)
+            self._pending_voice[(chat_id, status_msg_id)] = (
+                voice_msg_id,
+                status_msg_id,
+            )
+
+    async def cancel_pending_voice(
+        self, chat_id: str, reply_id: str
+    ) -> tuple[str, str] | None:
+        """Cancel a pending voice transcription. Returns (voice_msg_id, status_msg_id) if found."""
+        async with self._pending_voice_lock:
+            entry = self._pending_voice.pop((chat_id, reply_id), None)
+            if entry is None:
+                return None
+            voice_msg_id, status_msg_id = entry
+            self._pending_voice.pop((chat_id, voice_msg_id), None)
+            self._pending_voice.pop((chat_id, status_msg_id), None)
+            return (voice_msg_id, status_msg_id)
+
+    async def _is_voice_still_pending(self, chat_id: str, voice_msg_id: str) -> bool:
+        """Check if a voice note is still pending (not cancelled)."""
+        async with self._pending_voice_lock:
+            return (chat_id, voice_msg_id) in self._pending_voice
+
+    def _get_audio_attachment(self, message: Any) -> Any | None:
+        """Return first audio attachment, or None."""
+        for att in message.attachments:
+            ct = (att.content_type or "").lower()
+            fn = (att.filename or "").lower()
+            if ct.startswith("audio/") or any(
+                fn.endswith(ext) for ext in AUDIO_EXTENSIONS
+            ):
+                return att
+        return None
+
+    async def _handle_voice_note(
+        self, message: Any, attachment: Any, channel_id: str
+    ) -> bool:
+        """Handle voice/audio attachment. Returns True if handled."""
+        from config.settings import get_settings
+
+        settings = get_settings()
+        if not settings.voice_note_enabled:
+            await message.reply("Voice notes are disabled.")
+            return True
+
+        if not self._message_handler:
+            return False
+
+        status_msg_id = await self.queue_send_message(
+            channel_id,
+            format_status_discord("Transcribing voice note..."),
+            reply_to=str(message.id),
+            fire_and_forget=False,
+        )
+
+        user_id = str(message.author.id)
+        message_id = str(message.id)
+        await self._register_pending_voice(channel_id, message_id, str(status_msg_id))
+        reply_to = (
+            str(message.reference.message_id)
+            if message.reference and message.reference.message_id
+            else None
+        )
+
+        ext = ".ogg"
+        fn = (attachment.filename or "").lower()
+        for e in AUDIO_EXTENSIONS:
+            if fn.endswith(e):
+                ext = e
+                break
+        ct = attachment.content_type or "audio/ogg"
+        if "mp4" in ct or "m4a" in fn:
+            ext = ".m4a" if "m4a" in fn else ".mp4"
+        elif "mp3" in ct or fn.endswith(".mp3"):
+            ext = ".mp3"
+
+        with tempfile.NamedTemporaryFile(suffix=ext, delete=False) as tmp:
+            tmp_path = Path(tmp.name)
+
+        try:
+            await attachment.save(str(tmp_path))
+
+            from ..transcription import transcribe_audio
+
+            transcribed = await asyncio.to_thread(
+                transcribe_audio,
+                tmp_path,
+                ct,
+                whisper_model=settings.whisper_model,
+                whisper_device=settings.whisper_device,
+            )
+
+            if not await self._is_voice_still_pending(channel_id, message_id):
+                await self.queue_delete_message(channel_id, str(status_msg_id))
+                return True
+
+            async with self._pending_voice_lock:
+                self._pending_voice.pop((channel_id, message_id), None)
+                self._pending_voice.pop((channel_id, str(status_msg_id)), None)
+
+            incoming = IncomingMessage(
+                text=transcribed,
+                chat_id=channel_id,
+                user_id=user_id,
+                message_id=message_id,
+                platform="discord",
+                reply_to_message_id=reply_to,
+                username=message.author.display_name,
+                raw_event=message,
+                status_message_id=status_msg_id,
+            )
+
+            logger.info(
+                "DISCORD_VOICE: chat_id={} message_id={} transcribed={!r}",
+                channel_id,
+                message_id,
+                (transcribed[:80] + "..." if len(transcribed) > 80 else transcribed),
+            )
+
+            await self._message_handler(incoming)
+            return True
+        except ValueError as e:
+            await message.reply(get_user_facing_error_message(e)[:200])
+            return True
+        except ImportError as e:
+            await message.reply(get_user_facing_error_message(e)[:200])
+            return True
+        except Exception as e:
+            logger.error(f"Voice transcription failed: {e}")
+            await message.reply(
+                "Could not transcribe voice note. Please try again or send text."
+            )
+            return True
+        finally:
+            with contextlib.suppress(OSError):
+                tmp_path.unlink(missing_ok=True)
+
+    async def _on_discord_message(self, message: Any) -> None:
+        """Handle incoming Discord messages."""
+        if message.author.bot:
+            return
+
+        channel_id = str(message.channel.id)
+
+        if not self.allowed_channel_ids or channel_id not in self.allowed_channel_ids:
+            return
+
+        # Handle voice/audio attachments when message has no text content
+        if not message.content:
+            audio_att = self._get_audio_attachment(message)
+            if audio_att:
+                await self._handle_voice_note(message, audio_att, channel_id)
+                return
+            return
+
+        user_id = str(message.author.id)
+        message_id = str(message.id)
+        reply_to = (
+            str(message.reference.message_id)
+            if message.reference and message.reference.message_id
+            else None
+        )
+
+        text_preview = (message.content or "")[:80]
+        if len(message.content or "") > 80:
+            text_preview += "..."
+        logger.info(
+            "DISCORD_MSG: chat_id={} message_id={} reply_to={} text_preview={!r}",
+            channel_id,
+            message_id,
+            reply_to,
+            text_preview,
+        )
+
+        if not self._message_handler:
+            return
+
+        incoming = IncomingMessage(
+            text=message.content,
+            chat_id=channel_id,
+            user_id=user_id,
+            message_id=message_id,
+            platform="discord",
+            reply_to_message_id=reply_to,
+            username=message.author.display_name,
+            raw_event=message,
+        )
+
+        try:
+            await self._message_handler(incoming)
+        except Exception as e:
+            logger.error(f"Error handling message: {e}")
+            with contextlib.suppress(Exception):
+                await self.send_message(
+                    channel_id,
+                    format_status_discord(
+                        "Error:", get_user_facing_error_message(e)[:200]
+                    ),
+                    reply_to=message_id,
+                )
+
+    def _truncate(self, text: str, limit: int = DISCORD_MESSAGE_LIMIT) -> str:
+        """Truncate text to Discord's message limit."""
+        if len(text) <= limit:
+            return text
+        return text[: limit - 3] + "..."
+
+    async def start(self) -> None:
+        """Initialize and connect to Discord."""
+        if not self.bot_token:
+            raise ValueError("DISCORD_BOT_TOKEN is required")
+
+        from ..limiter import MessagingRateLimiter
+
+        self._limiter = await MessagingRateLimiter.get_instance()
+
+        self._start_task = asyncio.create_task(
+            self._client.start(self.bot_token),
+            name="discord-client-start",
+        )
+
+        max_wait = 30
+        waited = 0
+        while not self._connected and waited < max_wait:
+            await asyncio.sleep(0.5)
+            waited += 0.5
+
+        if not self._connected:
+            raise RuntimeError("Discord client failed to connect within timeout")
+
+        logger.info("Discord platform started")
+
+    async def stop(self) -> None:
+        """Stop the bot."""
+        if self._client.is_closed():
+            self._connected = False
+            return
+
+        await self._client.close()
+        if self._start_task and not self._start_task.done():
+            try:
+                await asyncio.wait_for(self._start_task, timeout=5.0)
+            except TimeoutError, asyncio.CancelledError:
+                self._start_task.cancel()
+                with contextlib.suppress(asyncio.CancelledError):
+                    await self._start_task
+
+        self._connected = False
+        logger.info("Discord platform stopped")
+
+    async def send_message(
+        self,
+        chat_id: str,
+        text: str,
+        reply_to: str | None = None,
+        parse_mode: str | None = None,
+        message_thread_id: str | None = None,
+    ) -> str:
+        """Send a message to a channel."""
+        channel = self._client.get_channel(int(chat_id))
+        if not channel or not hasattr(channel, "send"):
+            raise RuntimeError(f"Channel {chat_id} not found")
+
+        text = self._truncate(text)
+        channel = cast(Any, channel)
+
+        discord = _get_discord()
+        if reply_to:
+            ref = discord.MessageReference(
+                message_id=int(reply_to),
+                channel_id=int(chat_id),
+            )
+            msg = await channel.send(content=text, reference=ref)
+        else:
+            msg = await channel.send(content=text)
+
+        return str(msg.id)
+
+    async def edit_message(
+        self,
+        chat_id: str,
+        message_id: str,
+        text: str,
+        parse_mode: str | None = None,
+    ) -> None:
+        """Edit an existing message."""
+        channel = self._client.get_channel(int(chat_id))
+        if not channel or not hasattr(channel, "fetch_message"):
+            raise RuntimeError(f"Channel {chat_id} not found")
+
+        discord = _get_discord()
+        channel = cast(Any, channel)
+        try:
+            msg = await channel.fetch_message(int(message_id))
+        except discord.NotFound:
+            return
+
+        text = self._truncate(text)
+        await msg.edit(content=text)
+
+    async def delete_message(
+        self,
+        chat_id: str,
+        message_id: str,
+    ) -> None:
+        """Delete a message from a channel."""
+        channel = self._client.get_channel(int(chat_id))
+        if not channel or not hasattr(channel, "fetch_message"):
+            return
+
+        discord = _get_discord()
+        channel = cast(Any, channel)
+        try:
+            msg = await channel.fetch_message(int(message_id))
+            await msg.delete()
+        except discord.NotFound, discord.Forbidden:
+            pass
+
+    async def delete_messages(self, chat_id: str, message_ids: list[str]) -> None:
+        """Delete multiple messages (best-effort)."""
+        for mid in message_ids:
+            await self.delete_message(chat_id, mid)
+
+    async def queue_send_message(
+        self,
+        chat_id: str,
+        text: str,
+        reply_to: str | None = None,
+        parse_mode: str | None = None,
+        fire_and_forget: bool = True,
+        message_thread_id: str | None = None,
+    ) -> str | None:
+        """Enqueue a message to be sent."""
+        if not self._limiter:
+            return await self.send_message(
+                chat_id, text, reply_to, parse_mode, message_thread_id
+            )
+
+        async def _send():
+            return await self.send_message(
+                chat_id, text, reply_to, parse_mode, message_thread_id
+            )
+
+        if fire_and_forget:
+            self._limiter.fire_and_forget(_send)
+            return None
+        return await self._limiter.enqueue(_send)
+
+    async def queue_edit_message(
+        self,
+        chat_id: str,
+        message_id: str,
+        text: str,
+        parse_mode: str | None = None,
+        fire_and_forget: bool = True,
+    ) -> None:
+        """Enqueue a message edit."""
+        if not self._limiter:
+            await self.edit_message(chat_id, message_id, text, parse_mode)
+            return
+
+        async def _edit():
+            await self.edit_message(chat_id, message_id, text, parse_mode)
+
+        dedup_key = f"edit:{chat_id}:{message_id}"
+        if fire_and_forget:
+            self._limiter.fire_and_forget(_edit, dedup_key=dedup_key)
+        else:
+            await self._limiter.enqueue(_edit, dedup_key=dedup_key)
+
+    async def queue_delete_message(
+        self,
+        chat_id: str,
+        message_id: str,
+        fire_and_forget: bool = True,
+    ) -> None:
+        """Enqueue a message delete."""
+        if not self._limiter:
+            await self.delete_message(chat_id, message_id)
+            return
+
+        async def _delete():
+            await self.delete_message(chat_id, message_id)
+
+        dedup_key = f"del:{chat_id}:{message_id}"
+        if fire_and_forget:
+            self._limiter.fire_and_forget(_delete, dedup_key=dedup_key)
+        else:
+            await self._limiter.enqueue(_delete, dedup_key=dedup_key)
+
+    async def queue_delete_messages(
+        self,
+        chat_id: str,
+        message_ids: list[str],
+        fire_and_forget: bool = True,
+    ) -> None:
+        """Enqueue a bulk delete."""
+        if not message_ids:
+            return
+
+        if not self._limiter:
+            await self.delete_messages(chat_id, message_ids)
+            return
+
+        async def _bulk():
+            await self.delete_messages(chat_id, message_ids)
+
+        dedup_key = f"del_bulk:{chat_id}:{hash(tuple(message_ids))}"
+        if fire_and_forget:
+            self._limiter.fire_and_forget(_bulk, dedup_key=dedup_key)
+        else:
+            await self._limiter.enqueue(_bulk, dedup_key=dedup_key)
+
+    def fire_and_forget(self, task: Awaitable[Any]) -> None:
+        """Execute a coroutine without awaiting it."""
+        if asyncio.iscoroutine(task):
+            _ = asyncio.create_task(task)
+        else:
+            _ = asyncio.ensure_future(task)
+
+    def on_message(
+        self,
+        handler: Callable[[IncomingMessage], Awaitable[None]],
+    ) -> None:
+        """Register a message handler callback."""
+        self._message_handler = handler
+
+    @property
+    def is_connected(self) -> bool:
+        """Check if connected."""
+        return self._connected

Claude_Code/messaging/platforms/factory.py

@@ -0,0 +1,56 @@
+"""Messaging platform factory.
+
+Creates the appropriate messaging platform adapter based on configuration.
+To add a new platform (e.g. Discord, Slack):
+1. Create a new class implementing MessagingPlatform in messaging/platforms/
+2. Add a case to create_messaging_platform() below
+"""
+
+from loguru import logger
+
+from .base import MessagingPlatform
+
+
+def create_messaging_platform(
+    platform_type: str,
+    **kwargs,
+) -> MessagingPlatform | None:
+    """Create a messaging platform instance based on type.
+
+    Args:
+        platform_type: Platform identifier ("telegram", "discord", etc.)
+        **kwargs: Platform-specific configuration passed to the constructor.
+
+    Returns:
+        Configured MessagingPlatform instance, or None if not configured.
+    """
+    if platform_type == "telegram":
+        bot_token = kwargs.get("bot_token")
+        if not bot_token:
+            logger.info("No Telegram bot token configured, skipping platform setup")
+            return None
+
+        from .telegram import TelegramPlatform
+
+        return TelegramPlatform(
+            bot_token=bot_token,
+            allowed_user_id=kwargs.get("allowed_user_id"),
+        )
+
+    if platform_type == "discord":
+        bot_token = kwargs.get("discord_bot_token")
+        if not bot_token:
+            logger.info("No Discord bot token configured, skipping platform setup")
+            return None
+
+        from .discord import DiscordPlatform
+
+        return DiscordPlatform(
+            bot_token=bot_token,
+            allowed_channel_ids=kwargs.get("allowed_discord_channels"),
+        )
+
+    logger.warning(
+        f"Unknown messaging platform: '{platform_type}'. Supported: 'telegram', 'discord'"
+    )
+    return None

Claude_Code/messaging/platforms/telegram.py

@@ -0,0 +1,661 @@
+"""
+Telegram Platform Adapter
+
+Implements MessagingPlatform for Telegram using python-telegram-bot.
+"""
+
+import asyncio
+import contextlib
+import os
+import tempfile
+from pathlib import Path
+
+# Opt-in to future behavior for python-telegram-bot (retry_after as timedelta)
+# This must be set BEFORE importing telegram.error
+os.environ["PTB_TIMEDELTA"] = "1"
+
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, Any
+
+from loguru import logger
+
+from providers.common import get_user_facing_error_message
+
+if TYPE_CHECKING:
+    from telegram import Update
+    from telegram.ext import ContextTypes
+
+from ..models import IncomingMessage
+from ..rendering.telegram_markdown import escape_md_v2, format_status
+from .base import MessagingPlatform
+
+# Optional import - python-telegram-bot may not be installed
+try:
+    from telegram import Update
+    from telegram.error import NetworkError, RetryAfter, TelegramError
+    from telegram.ext import (
+        Application,
+        CommandHandler,
+        ContextTypes,
+        MessageHandler,
+        filters,
+    )
+    from telegram.request import HTTPXRequest
+
+    TELEGRAM_AVAILABLE = True
+except ImportError:
+    TELEGRAM_AVAILABLE = False
+
+
+class TelegramPlatform(MessagingPlatform):
+    """
+    Telegram messaging platform adapter.
+
+    Uses python-telegram-bot (BoT API) for Telegram access.
+    Requires a Bot Token from @BotFather.
+    """
+
+    name = "telegram"
+
+    def __init__(
+        self,
+        bot_token: str | None = None,
+        allowed_user_id: str | None = None,
+    ):
+        if not TELEGRAM_AVAILABLE:
+            raise ImportError(
+                "python-telegram-bot is required. Install with: pip install python-telegram-bot"
+            )
+
+        self.bot_token = bot_token or os.getenv("TELEGRAM_BOT_TOKEN")
+        self.allowed_user_id = allowed_user_id or os.getenv("ALLOWED_TELEGRAM_USER_ID")
+
+        if not self.bot_token:
+            # We don't raise here to allow instantiation for testing/conditional logic,
+            # but start() will fail.
+            logger.warning("TELEGRAM_BOT_TOKEN not set")
+
+        self._application: Application | None = None
+        self._message_handler: Callable[[IncomingMessage], Awaitable[None]] | None = (
+            None
+        )
+        self._connected = False
+        self._limiter: Any | None = None  # Will be MessagingRateLimiter
+        # Pending voice transcriptions: (chat_id, msg_id) -> (voice_msg_id, status_msg_id)
+        self._pending_voice: dict[tuple[str, str], tuple[str, str]] = {}
+        self._pending_voice_lock = asyncio.Lock()
+
+    async def _register_pending_voice(
+        self, chat_id: str, voice_msg_id: str, status_msg_id: str
+    ) -> None:
+        """Register a voice note as pending transcription (for /clear reply during transcription)."""
+        async with self._pending_voice_lock:
+            self._pending_voice[(chat_id, voice_msg_id)] = (voice_msg_id, status_msg_id)
+            self._pending_voice[(chat_id, status_msg_id)] = (
+                voice_msg_id,
+                status_msg_id,
+            )
+
+    async def cancel_pending_voice(
+        self, chat_id: str, reply_id: str
+    ) -> tuple[str, str] | None:
+        """Cancel a pending voice transcription. Returns (voice_msg_id, status_msg_id) if found."""
+        async with self._pending_voice_lock:
+            entry = self._pending_voice.pop((chat_id, reply_id), None)
+            if entry is None:
+                return None
+            voice_msg_id, status_msg_id = entry
+            self._pending_voice.pop((chat_id, voice_msg_id), None)
+            self._pending_voice.pop((chat_id, status_msg_id), None)
+            return (voice_msg_id, status_msg_id)
+
+    async def _is_voice_still_pending(self, chat_id: str, voice_msg_id: str) -> bool:
+        """Check if a voice note is still pending (not cancelled)."""
+        async with self._pending_voice_lock:
+            return (chat_id, voice_msg_id) in self._pending_voice
+
+    async def start(self) -> None:
+        """Initialize and connect to Telegram."""
+        if not self.bot_token:
+            raise ValueError("TELEGRAM_BOT_TOKEN is required")
+
+        # Configure request with longer timeouts
+        request = HTTPXRequest(
+            connection_pool_size=8, connect_timeout=30.0, read_timeout=30.0
+        )
+
+        # Build Application
+        builder = Application.builder().token(self.bot_token).request(request)
+        self._application = builder.build()
+
+        # Register Internal Handlers
+        # We catch ALL text messages and commands to forward them
+        self._application.add_handler(
+            MessageHandler(filters.TEXT & (~filters.COMMAND), self._on_telegram_message)
+        )
+        self._application.add_handler(CommandHandler("start", self._on_start_command))
+        # Catch-all for other commands if needed, or let them fall through
+        self._application.add_handler(
+            MessageHandler(filters.COMMAND, self._on_telegram_message)
+        )
+        # Voice note handler
+        self._application.add_handler(
+            MessageHandler(filters.VOICE, self._on_telegram_voice)
+        )
+
+        # Initialize internal components with retry logic
+        max_retries = 3
+        for attempt in range(max_retries):
+            try:
+                await self._application.initialize()
+                await self._application.start()
+
+                # Start polling (non-blocking way for integration)
+                if self._application.updater:
+                    await self._application.updater.start_polling(
+                        drop_pending_updates=False
+                    )
+
+                self._connected = True
+                break
+            except (NetworkError, Exception) as e:
+                if attempt < max_retries - 1:
+                    wait_time = 2 * (attempt + 1)
+                    logger.warning(
+                        f"Connection failed (attempt {attempt + 1}/{max_retries}): {e}. Retrying in {wait_time}s..."
+                    )
+                    await asyncio.sleep(wait_time)
+                else:
+                    logger.error(f"Failed to connect after {max_retries} attempts")
+                    raise
+
+        # Initialize rate limiter
+        from ..limiter import MessagingRateLimiter
+
+        self._limiter = await MessagingRateLimiter.get_instance()
+
+        # Send startup notification
+        try:
+            target = self.allowed_user_id
+            if target:
+                startup_text = (
+                    f"🚀 *{escape_md_v2('Claude Code Proxy is online!')}* "
+                    f"{escape_md_v2('(Bot API)')}"
+                )
+                await self.send_message(
+                    target,
+                    startup_text,
+                )
+        except Exception as e:
+            logger.warning(f"Could not send startup message: {e}")
+
+        logger.info("Telegram platform started (Bot API)")
+
+    async def stop(self) -> None:
+        """Stop the bot."""
+        if self._application and self._application.updater:
+            await self._application.updater.stop()
+            await self._application.stop()
+            await self._application.shutdown()
+
+        self._connected = False
+        logger.info("Telegram platform stopped")
+
+    async def _with_retry(
+        self, func: Callable[..., Awaitable[Any]], *args, **kwargs
+    ) -> Any:
+        """Helper to execute a function with exponential backoff on network errors."""
+        max_retries = 3
+        for attempt in range(max_retries):
+            try:
+                return await func(*args, **kwargs)
+            except (TimeoutError, NetworkError) as e:
+                if "Message is not modified" in str(e):
+                    return None
+                if attempt < max_retries - 1:
+                    wait_time = 2**attempt  # 1s, 2s, 4s
+                    logger.warning(
+                        f"Telegram API network error (attempt {attempt + 1}/{max_retries}): {e}. Retrying in {wait_time}s..."
+                    )
+                    await asyncio.sleep(wait_time)
+                else:
+                    logger.error(
+                        f"Telegram API failed after {max_retries} attempts: {e}"
+                    )
+                    raise
+            except RetryAfter as e:
+                # Telegram explicitly tells us to wait (PTB_TIMEDELTA: retry_after is timedelta)
+                from datetime import timedelta
+
+                retry_after = e.retry_after
+                if isinstance(retry_after, timedelta):
+                    wait_secs = retry_after.total_seconds()
+                else:
+                    wait_secs = float(retry_after)
+
+                logger.warning(f"Rate limited by Telegram, waiting {wait_secs}s...")
+                await asyncio.sleep(wait_secs)
+                # We don't increment attempt here, as this is a specific instruction
+                return await func(*args, **kwargs)
+            except TelegramError as e:
+                # Non-network Telegram errors
+                err_lower = str(e).lower()
+                if "message is not modified" in err_lower:
+                    return None
+                # Best-effort no-op cases (common during chat cleanup / /clear).
+                if any(
+                    x in err_lower
+                    for x in [
+                        "message to edit not found",
+                        "message to delete not found",
+                        "message can't be deleted",
+                        "message can't be edited",
+                        "not enough rights to delete",
+                    ]
+                ):
+                    return None
+                if "Can't parse entities" in str(e) and kwargs.get("parse_mode"):
+                    logger.warning("Markdown failed, retrying without parse_mode")
+                    kwargs["parse_mode"] = None
+                    return await func(*args, **kwargs)
+                raise
+
+    async def send_message(
+        self,
+        chat_id: str,
+        text: str,
+        reply_to: str | None = None,
+        parse_mode: str | None = "MarkdownV2",
+        message_thread_id: str | None = None,
+    ) -> str:
+        """Send a message to a chat."""
+        app = self._application
+        if not app or not app.bot:
+            raise RuntimeError("Telegram application or bot not initialized")
+
+        async def _do_send(parse_mode=parse_mode):
+            bot = app.bot
+            kwargs: dict[str, Any] = {
+                "chat_id": chat_id,
+                "text": text,
+                "reply_to_message_id": int(reply_to) if reply_to else None,
+                "parse_mode": parse_mode,
+            }
+            if message_thread_id is not None:
+                kwargs["message_thread_id"] = int(message_thread_id)
+            msg = await bot.send_message(**kwargs)
+            return str(msg.message_id)
+
+        return await self._with_retry(_do_send, parse_mode=parse_mode)
+
+    async def edit_message(
+        self,
+        chat_id: str,
+        message_id: str,
+        text: str,
+        parse_mode: str | None = "MarkdownV2",
+    ) -> None:
+        """Edit an existing message."""
+        app = self._application
+        if not app or not app.bot:
+            raise RuntimeError("Telegram application or bot not initialized")
+
+        async def _do_edit(parse_mode=parse_mode):
+            bot = app.bot
+            await bot.edit_message_text(
+                chat_id=chat_id,
+                message_id=int(message_id),
+                text=text,
+                parse_mode=parse_mode,
+            )
+
+        await self._with_retry(_do_edit, parse_mode=parse_mode)
+
+    async def delete_message(
+        self,
+        chat_id: str,
+        message_id: str,
+    ) -> None:
+        """Delete a message from a chat."""
+        app = self._application
+        if not app or not app.bot:
+            raise RuntimeError("Telegram application or bot not initialized")
+
+        async def _do_delete():
+            bot = app.bot
+            await bot.delete_message(chat_id=chat_id, message_id=int(message_id))
+
+        await self._with_retry(_do_delete)
+
+    async def delete_messages(self, chat_id: str, message_ids: list[str]) -> None:
+        """Delete multiple messages (best-effort)."""
+        if not message_ids:
+            return
+        app = self._application
+        if not app or not app.bot:
+            raise RuntimeError("Telegram application or bot not initialized")
+
+        # PTB supports bulk deletion via delete_messages; fall back to per-message.
+        bot = app.bot
+        if hasattr(bot, "delete_messages"):
+
+            async def _do_bulk():
+                mids = []
+                for mid in message_ids:
+                    try:
+                        mids.append(int(mid))
+                    except Exception:
+                        continue
+                if not mids:
+                    return None
+                # delete_messages accepts a sequence of ints (up to 100).
+                await bot.delete_messages(chat_id=chat_id, message_ids=mids)
+
+            await self._with_retry(_do_bulk)
+            return
+
+        for mid in message_ids:
+            await self.delete_message(chat_id, mid)
+
+    async def queue_send_message(
+        self,
+        chat_id: str,
+        text: str,
+        reply_to: str | None = None,
+        parse_mode: str | None = "MarkdownV2",
+        fire_and_forget: bool = True,
+        message_thread_id: str | None = None,
+    ) -> str | None:
+        """Enqueue a message to be sent (using limiter)."""
+        # Note: Bot API handles limits better, but we still use our limiter for nice queuing
+        if not self._limiter:
+            return await self.send_message(
+                chat_id, text, reply_to, parse_mode, message_thread_id
+            )
+
+        async def _send():
+            return await self.send_message(
+                chat_id, text, reply_to, parse_mode, message_thread_id
+            )
+
+        if fire_and_forget:
+            self._limiter.fire_and_forget(_send)
+            return None
+        else:
+            return await self._limiter.enqueue(_send)
+
+    async def queue_edit_message(
+        self,
+        chat_id: str,
+        message_id: str,
+        text: str,
+        parse_mode: str | None = "MarkdownV2",
+        fire_and_forget: bool = True,
+    ) -> None:
+        """Enqueue a message edit."""
+        if not self._limiter:
+            return await self.edit_message(chat_id, message_id, text, parse_mode)
+
+        async def _edit():
+            return await self.edit_message(chat_id, message_id, text, parse_mode)
+
+        dedup_key = f"edit:{chat_id}:{message_id}"
+        if fire_and_forget:
+            self._limiter.fire_and_forget(_edit, dedup_key=dedup_key)
+        else:
+            await self._limiter.enqueue(_edit, dedup_key=dedup_key)
+
+    async def queue_delete_message(
+        self,
+        chat_id: str,
+        message_id: str,
+        fire_and_forget: bool = True,
+    ) -> None:
+        """Enqueue a message delete."""
+        if not self._limiter:
+            return await self.delete_message(chat_id, message_id)
+
+        async def _delete():
+            return await self.delete_message(chat_id, message_id)
+
+        dedup_key = f"del:{chat_id}:{message_id}"
+        if fire_and_forget:
+            self._limiter.fire_and_forget(_delete, dedup_key=dedup_key)
+        else:
+            await self._limiter.enqueue(_delete, dedup_key=dedup_key)
+
+    async def queue_delete_messages(
+        self,
+        chat_id: str,
+        message_ids: list[str],
+        fire_and_forget: bool = True,
+    ) -> None:
+        """Enqueue a bulk delete (if supported) or a sequence of deletes."""
+        if not message_ids:
+            return
+
+        if not self._limiter:
+            return await self.delete_messages(chat_id, message_ids)
+
+        async def _bulk():
+            return await self.delete_messages(chat_id, message_ids)
+
+        # Dedup by the chunk content; okay to be coarse here.
+        dedup_key = f"del_bulk:{chat_id}:{hash(tuple(message_ids))}"
+        if fire_and_forget:
+            self._limiter.fire_and_forget(_bulk, dedup_key=dedup_key)
+        else:
+            await self._limiter.enqueue(_bulk, dedup_key=dedup_key)
+
+    def fire_and_forget(self, task: Awaitable[Any]) -> None:
+        """Execute a coroutine without awaiting it."""
+        if asyncio.iscoroutine(task):
+            _ = asyncio.create_task(task)
+        else:
+            _ = asyncio.ensure_future(task)
+
+    def on_message(
+        self,
+        handler: Callable[[IncomingMessage], Awaitable[None]],
+    ) -> None:
+        """Register a message handler callback."""
+        self._message_handler = handler
+
+    @property
+    def is_connected(self) -> bool:
+        """Check if connected."""
+        return self._connected
+
+    async def _on_start_command(
+        self, update: Update, context: ContextTypes.DEFAULT_TYPE
+    ) -> None:
+        """Handle /start command."""
+        if update.message:
+            await update.message.reply_text("👋 Hello! I am the Claude Code Proxy Bot.")
+        # We can also treat this as a message if we want it to trigger something
+        await self._on_telegram_message(update, context)
+
+    async def _on_telegram_message(
+        self, update: Update, context: ContextTypes.DEFAULT_TYPE
+    ) -> None:
+        """Handle incoming updates."""
+        if (
+            not update.message
+            or not update.message.text
+            or not update.effective_user
+            or not update.effective_chat
+        ):
+            return
+
+        user_id = str(update.effective_user.id)
+        chat_id = str(update.effective_chat.id)
+
+        # Security check
+        if self.allowed_user_id and user_id != str(self.allowed_user_id).strip():
+            logger.warning(f"Unauthorized access attempt from {user_id}")
+            return
+
+        message_id = str(update.message.message_id)
+        reply_to = (
+            str(update.message.reply_to_message.message_id)
+            if update.message.reply_to_message
+            else None
+        )
+        thread_id = (
+            str(update.message.message_thread_id)
+            if getattr(update.message, "message_thread_id", None) is not None
+            else None
+        )
+        text_preview = (update.message.text or "")[:80]
+        if len(update.message.text or "") > 80:
+            text_preview += "..."
+        logger.info(
+            "TELEGRAM_MSG: chat_id={} message_id={} reply_to={} text_preview={!r}",
+            chat_id,
+            message_id,
+            reply_to,
+            text_preview,
+        )
+
+        if not self._message_handler:
+            return
+
+        incoming = IncomingMessage(
+            text=update.message.text,
+            chat_id=chat_id,
+            user_id=user_id,
+            message_id=message_id,
+            platform="telegram",
+            reply_to_message_id=reply_to,
+            message_thread_id=thread_id,
+            raw_event=update,
+        )
+
+        try:
+            await self._message_handler(incoming)
+        except Exception as e:
+            logger.error(f"Error handling message: {e}")
+            with contextlib.suppress(Exception):
+                await self.send_message(
+                    chat_id,
+                    f"❌ *{escape_md_v2('Error:')}* {escape_md_v2(get_user_facing_error_message(e)[:200])}",
+                    reply_to=incoming.message_id,
+                    message_thread_id=thread_id,
+                    parse_mode="MarkdownV2",
+                )
+
+    async def _on_telegram_voice(
+        self, update: Update, context: ContextTypes.DEFAULT_TYPE
+    ) -> None:
+        """Handle incoming voice messages."""
+        if (
+            not update.message
+            or not update.message.voice
+            or not update.effective_user
+            or not update.effective_chat
+        ):
+            return
+
+        from config.settings import get_settings
+
+        settings = get_settings()
+        if not settings.voice_note_enabled:
+            await update.message.reply_text("Voice notes are disabled.")
+            return
+
+        user_id = str(update.effective_user.id)
+        chat_id = str(update.effective_chat.id)
+
+        if self.allowed_user_id and user_id != str(self.allowed_user_id).strip():
+            logger.warning(f"Unauthorized voice access attempt from {user_id}")
+            return
+
+        if not self._message_handler:
+            return
+
+        thread_id = (
+            str(update.message.message_thread_id)
+            if getattr(update.message, "message_thread_id", None) is not None
+            else None
+        )
+        status_msg_id = await self.queue_send_message(
+            chat_id,
+            format_status("⏳", "Transcribing voice note..."),
+            reply_to=str(update.message.message_id),
+            parse_mode="MarkdownV2",
+            fire_and_forget=False,
+            message_thread_id=thread_id,
+        )
+
+        message_id = str(update.message.message_id)
+        await self._register_pending_voice(chat_id, message_id, str(status_msg_id))
+        reply_to = (
+            str(update.message.reply_to_message.message_id)
+            if update.message.reply_to_message
+            else None
+        )
+
+        voice = update.message.voice
+        suffix = ".ogg"
+        if voice.mime_type and "mpeg" in voice.mime_type:
+            suffix = ".mp3"
+        elif voice.mime_type and "mp4" in voice.mime_type:
+            suffix = ".mp4"
+
+        with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp:
+            tmp_path = Path(tmp.name)
+
+        try:
+            tg_file = await context.bot.get_file(voice.file_id)
+            await tg_file.download_to_drive(custom_path=str(tmp_path))
+
+            from ..transcription import transcribe_audio
+
+            transcribed = await asyncio.to_thread(
+                transcribe_audio,
+                tmp_path,
+                voice.mime_type or "audio/ogg",
+                whisper_model=settings.whisper_model,
+                whisper_device=settings.whisper_device,
+            )
+
+            if not await self._is_voice_still_pending(chat_id, message_id):
+                await self.queue_delete_message(chat_id, str(status_msg_id))
+                return
+
+            async with self._pending_voice_lock:
+                self._pending_voice.pop((chat_id, message_id), None)
+                self._pending_voice.pop((chat_id, str(status_msg_id)), None)
+
+            incoming = IncomingMessage(
+                text=transcribed,
+                chat_id=chat_id,
+                user_id=user_id,
+                message_id=message_id,
+                platform="telegram",
+                reply_to_message_id=reply_to,
+                message_thread_id=thread_id,
+                raw_event=update,
+                status_message_id=status_msg_id,
+            )
+
+            logger.info(
+                "TELEGRAM_VOICE: chat_id={} message_id={} transcribed={!r}",
+                chat_id,
+                message_id,
+                (transcribed[:80] + "..." if len(transcribed) > 80 else transcribed),
+            )
+
+            await self._message_handler(incoming)
+        except ValueError as e:
+            await update.message.reply_text(get_user_facing_error_message(e)[:200])
+        except ImportError as e:
+            await update.message.reply_text(get_user_facing_error_message(e)[:200])
+        except Exception as e:
+            logger.error(f"Voice transcription failed: {e}")
+            await update.message.reply_text(
+                "Could not transcribe voice note. Please try again or send text."
+            )
+        finally:
+            with contextlib.suppress(OSError):
+                tmp_path.unlink(missing_ok=True)

Claude_Code/messaging/rendering/__init__.py

@@ -0,0 +1,41 @@
+"""Markdown rendering utilities for messaging platforms."""
+
+from .discord_markdown import (
+    discord_bold,
+    discord_code_inline,
+    escape_discord,
+    escape_discord_code,
+    format_status_discord,
+    render_markdown_to_discord,
+)
+from .discord_markdown import (
+    format_status as format_status_discord_fn,
+)
+from .telegram_markdown import (
+    escape_md_v2,
+    escape_md_v2_code,
+    escape_md_v2_link_url,
+    mdv2_bold,
+    mdv2_code_inline,
+    render_markdown_to_mdv2,
+)
+from .telegram_markdown import (
+    format_status as format_status_telegram_fn,
+)
+
+__all__ = [
+    "discord_bold",
+    "discord_code_inline",
+    "escape_discord",
+    "escape_discord_code",
+    "escape_md_v2",
+    "escape_md_v2_code",
+    "escape_md_v2_link_url",
+    "format_status_discord",
+    "format_status_discord_fn",
+    "format_status_telegram_fn",
+    "mdv2_bold",
+    "mdv2_code_inline",
+    "render_markdown_to_discord",
+    "render_markdown_to_mdv2",
+]

Claude_Code/messaging/rendering/discord_markdown.py

@@ -0,0 +1,365 @@
+"""Discord markdown utilities.
+
+Discord uses standard markdown: **bold**, *italic*, `code`, ```code block```.
+Used by the message handler and Discord platform adapter.
+"""
+
+import re
+
+from markdown_it import MarkdownIt
+
+# Discord escapes: \ * _ ` ~ | >
+DISCORD_SPECIAL = set("\\*_`~|>")
+
+_MD = MarkdownIt("commonmark", {"html": False, "breaks": False})
+_MD.enable("strikethrough")
+_MD.enable("table")
+
+_TABLE_SEP_RE = re.compile(r"^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)+\|?\s*$")
+_FENCE_RE = re.compile(r"^\s*```")
+
+
+def _is_gfm_table_header_line(line: str) -> bool:
+    """Check if line is a GFM table header."""
+    if "|" not in line:
+        return False
+    if _TABLE_SEP_RE.match(line):
+        return False
+    stripped = line.strip()
+    parts = [p.strip() for p in stripped.strip("|").split("|")]
+    parts = [p for p in parts if p != ""]
+    return len(parts) >= 2
+
+
+def _normalize_gfm_tables(text: str) -> str:
+    """Insert blank line before detected tables outside code blocks."""
+    lines = text.splitlines()
+    if len(lines) < 2:
+        return text
+
+    out_lines: list[str] = []
+    in_fence = False
+
+    for idx, line in enumerate(lines):
+        if _FENCE_RE.match(line):
+            in_fence = not in_fence
+            out_lines.append(line)
+            continue
+
+        if (
+            not in_fence
+            and idx + 1 < len(lines)
+            and _is_gfm_table_header_line(line)
+            and _TABLE_SEP_RE.match(lines[idx + 1])
+            and out_lines
+            and out_lines[-1].strip() != ""
+        ):
+            m = re.match(r"^(\s*)", line)
+            indent = m.group(1) if m else ""
+            out_lines.append(indent)
+
+        out_lines.append(line)
+
+    return "\n".join(out_lines)
+
+
+def escape_discord(text: str) -> str:
+    """Escape text for Discord markdown (bold, italic, etc.)."""
+    return "".join(f"\\{ch}" if ch in DISCORD_SPECIAL else ch for ch in text)
+
+
+def escape_discord_code(text: str) -> str:
+    """Escape text for Discord code spans/blocks."""
+    return text.replace("\\", "\\\\").replace("`", "\\`")
+
+
+def discord_bold(text: str) -> str:
+    """Format text as bold in Discord (uses **)."""
+    return f"**{escape_discord(text)}**"
+
+
+def discord_code_inline(text: str) -> str:
+    """Format text as inline code in Discord."""
+    return f"`{escape_discord_code(text)}`"
+
+
+def format_status_discord(label: str, suffix: str | None = None) -> str:
+    """Format a status message for Discord (label in bold, optional suffix)."""
+    base = discord_bold(label)
+    if suffix:
+        return f"{base} {escape_discord(suffix)}"
+    return base
+
+
+def format_status(emoji: str, label: str, suffix: str | None = None) -> str:
+    """Format a status message with emoji for Discord (matches Telegram API)."""
+    base = f"{emoji} {discord_bold(label)}"
+    if suffix:
+        return f"{base} {escape_discord(suffix)}"
+    return base
+
+
+def render_markdown_to_discord(text: str) -> str:
+    """Render common Markdown into Discord-compatible format."""
+    if not text:
+        return ""
+
+    text = _normalize_gfm_tables(text)
+    tokens = _MD.parse(text)
+
+    def render_inline_table_plain(children) -> str:
+        out: list[str] = []
+        for tok in children:
+            if tok.type == "text" or tok.type == "code_inline":
+                out.append(tok.content)
+            elif tok.type in {"softbreak", "hardbreak"}:
+                out.append(" ")
+            elif tok.type == "image" and tok.content:
+                out.append(tok.content)
+        return "".join(out)
+
+    def render_inline(children) -> str:
+        out: list[str] = []
+        i = 0
+        while i < len(children):
+            tok = children[i]
+            t = tok.type
+            if t == "text":
+                out.append(escape_discord(tok.content))
+            elif t in {"softbreak", "hardbreak"}:
+                out.append("\n")
+            elif t == "em_open" or t == "em_close":
+                out.append("*")
+            elif t == "strong_open" or t == "strong_close":
+                out.append("**")
+            elif t == "s_open" or t == "s_close":
+                out.append("~~")
+            elif t == "code_inline":
+                out.append(f"`{escape_discord_code(tok.content)}`")
+            elif t == "link_open":
+                href = ""
+                if tok.attrs:
+                    if isinstance(tok.attrs, dict):
+                        href = tok.attrs.get("href", "")
+                    else:
+                        for key, val in tok.attrs:
+                            if key == "href":
+                                href = val
+                                break
+                inner_tokens = []
+                i += 1
+                while i < len(children) and children[i].type != "link_close":
+                    inner_tokens.append(children[i])
+                    i += 1
+                link_text = ""
+                for child in inner_tokens:
+                    if child.type == "text" or child.type == "code_inline":
+                        link_text += child.content
+                out.append(f"[{escape_discord(link_text)}]({href})")
+            elif t == "image":
+                href = ""
+                alt = tok.content or ""
+                if tok.attrs:
+                    if isinstance(tok.attrs, dict):
+                        href = tok.attrs.get("src", "")
+                    else:
+                        for key, val in tok.attrs:
+                            if key == "src":
+                                href = val
+                                break
+                if alt:
+                    out.append(f"{escape_discord(alt)} ({href})")
+                else:
+                    out.append(href)
+            else:
+                out.append(escape_discord(tok.content or ""))
+            i += 1
+        return "".join(out)
+
+    out: list[str] = []
+    list_stack: list[dict] = []
+    pending_prefix: str | None = None
+    blockquote_level = 0
+    in_heading = False
+
+    def apply_blockquote(val: str) -> str:
+        if blockquote_level <= 0:
+            return val
+        prefix = "> " * blockquote_level
+        return prefix + val.replace("\n", "\n" + prefix)
+
+    i = 0
+    while i < len(tokens):
+        tok = tokens[i]
+        t = tok.type
+        if t == "paragraph_open":
+            pass
+        elif t == "paragraph_close":
+            out.append("\n")
+        elif t == "heading_open":
+            in_heading = True
+        elif t == "heading_close":
+            in_heading = False
+            out.append("\n")
+        elif t == "bullet_list_open":
+            list_stack.append({"type": "bullet", "index": 1})
+        elif t == "bullet_list_close":
+            if list_stack:
+                list_stack.pop()
+            out.append("\n")
+        elif t == "ordered_list_open":
+            start = 1
+            if tok.attrs:
+                if isinstance(tok.attrs, dict):
+                    val = tok.attrs.get("start")
+                    if val is not None:
+                        try:
+                            start = int(val)
+                        except TypeError, ValueError:
+                            start = 1
+                else:
+                    for key, val in tok.attrs:
+                        if key == "start":
+                            try:
+                                start = int(val)
+                            except TypeError, ValueError:
+                                start = 1
+                            break
+            list_stack.append({"type": "ordered", "index": start})
+        elif t == "ordered_list_close":
+            if list_stack:
+                list_stack.pop()
+            out.append("\n")
+        elif t == "list_item_open":
+            if list_stack:
+                top = list_stack[-1]
+                if top["type"] == "bullet":
+                    pending_prefix = "- "
+                else:
+                    pending_prefix = f"{top['index']}. "
+                    top["index"] += 1
+        elif t == "list_item_close":
+            out.append("\n")
+        elif t == "blockquote_open":
+            blockquote_level += 1
+        elif t == "blockquote_close":
+            blockquote_level = max(0, blockquote_level - 1)
+            out.append("\n")
+        elif t == "table_open":
+            if pending_prefix:
+                out.append(apply_blockquote(pending_prefix.rstrip()))
+                out.append("\n")
+                pending_prefix = None
+
+            rows: list[list[str]] = []
+            row_is_header: list[bool] = []
+
+            j = i + 1
+            in_thead = False
+            in_row = False
+            current_row: list[str] = []
+            current_row_header = False
+
+            in_cell = False
+            cell_parts: list[str] = []
+
+            while j < len(tokens):
+                tt = tokens[j].type
+                if tt == "thead_open":
+                    in_thead = True
+                elif tt == "thead_close":
+                    in_thead = False
+                elif tt == "tr_open":
+                    in_row = True
+                    current_row = []
+                    current_row_header = in_thead
+                elif tt in {"th_open", "td_open"}:
+                    in_cell = True
+                    cell_parts = []
+                elif tt == "inline" and in_cell:
+                    cell_parts.append(
+                        render_inline_table_plain(tokens[j].children or [])
+                    )
+                elif tt in {"th_close", "td_close"} and in_cell:
+                    cell = " ".join(cell_parts).strip()
+                    current_row.append(cell)
+                    in_cell = False
+                    cell_parts = []
+                elif tt == "tr_close" and in_row:
+                    rows.append(current_row)
+                    row_is_header.append(bool(current_row_header))
+                    in_row = False
+                elif tt == "table_close":
+                    break
+                j += 1
+
+            if rows:
+                col_count = max((len(r) for r in rows), default=0)
+                norm_rows: list[list[str]] = []
+                for r in rows:
+                    if len(r) < col_count:
+                        r = r + [""] * (col_count - len(r))
+                    norm_rows.append(r)
+
+                widths: list[int] = []
+                for c in range(col_count):
+                    w = max((len(r[c]) for r in norm_rows), default=0)
+                    widths.append(max(w, 3))
+
+                def fmt_row(
+                    r: list[str], _w: list[int] = widths, _c: int = col_count
+                ) -> str:
+                    cells = [r[c].ljust(_w[c]) for c in range(_c)]
+                    return "| " + " | ".join(cells) + " |"
+
+                def fmt_sep(_w: list[int] = widths, _c: int = col_count) -> str:
+                    cells = ["-" * _w[c] for c in range(_c)]
+                    return "| " + " | ".join(cells) + " |"
+
+                last_header_idx = -1
+                for idx, is_h in enumerate(row_is_header):
+                    if is_h:
+                        last_header_idx = idx
+
+                lines: list[str] = []
+                for idx, r in enumerate(norm_rows):
+                    lines.append(fmt_row(r))
+                    if idx == last_header_idx:
+                        lines.append(fmt_sep())
+
+                table_text = "\n".join(lines).rstrip()
+                out.append(f"```\n{escape_discord_code(table_text)}\n```")
+                out.append("\n")
+
+            i = j + 1
+            continue
+        elif t in {"code_block", "fence"}:
+            code = escape_discord_code(tok.content.rstrip("\n"))
+            out.append(f"```\n{code}\n```")
+            out.append("\n")
+        elif t == "inline":
+            rendered = render_inline(tok.children or [])
+            if in_heading:
+                rendered = f"**{render_inline(tok.children or [])}**"
+            if pending_prefix:
+                rendered = pending_prefix + rendered
+                pending_prefix = None
+            rendered = apply_blockquote(rendered)
+            out.append(rendered)
+        else:
+            if tok.content:
+                out.append(escape_discord(tok.content))
+        i += 1
+
+    return "".join(out).rstrip()
+
+
+__all__ = [
+    "discord_bold",
+    "discord_code_inline",
+    "escape_discord",
+    "escape_discord_code",
+    "format_status",
+    "format_status_discord",
+    "render_markdown_to_discord",
+]

Claude_Code/messaging/rendering/telegram_markdown.py

@@ -0,0 +1,380 @@
+"""Telegram MarkdownV2 utilities.
+
+Renders common Markdown into Telegram MarkdownV2 format.
+Used by the message handler and Telegram platform adapter.
+"""
+
+import re
+
+from markdown_it import MarkdownIt
+
+MDV2_SPECIAL_CHARS = set("\\_*[]()~`>#+-=|{}.!")
+MDV2_LINK_ESCAPE = set("\\)")
+
+_MD = MarkdownIt("commonmark", {"html": False, "breaks": False})
+_MD.enable("strikethrough")
+_MD.enable("table")
+
+_TABLE_SEP_RE = re.compile(r"^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)+\|?\s*$")
+_FENCE_RE = re.compile(r"^\s*```")
+
+
+def _is_gfm_table_header_line(line: str) -> bool:
+    """Check if line is a GFM table header (pipe-delimited, not separator)."""
+    if "|" not in line:
+        return False
+    if _TABLE_SEP_RE.match(line):
+        return False
+    stripped = line.strip()
+    parts = [p.strip() for p in stripped.strip("|").split("|")]
+    parts = [p for p in parts if p != ""]
+    return len(parts) >= 2
+
+
+def _normalize_gfm_tables(text: str) -> str:
+    """
+    Many LLMs emit tables immediately after a paragraph line (no blank line).
+    Markdown-it will treat that as a softbreak within the paragraph, so the
+    table extension won't trigger. Insert a blank line before detected tables.
+
+    We only do this outside fenced code blocks.
+    """
+    lines = text.splitlines()
+    if len(lines) < 2:
+        return text
+
+    out_lines: list[str] = []
+    in_fence = False
+
+    for idx, line in enumerate(lines):
+        if _FENCE_RE.match(line):
+            in_fence = not in_fence
+            out_lines.append(line)
+            continue
+
+        if (
+            not in_fence
+            and idx + 1 < len(lines)
+            and _is_gfm_table_header_line(line)
+            and _TABLE_SEP_RE.match(lines[idx + 1])
+            and out_lines
+            and out_lines[-1].strip() != ""
+        ):
+            m = re.match(r"^(\s*)", line)
+            indent = m.group(1) if m else ""
+            out_lines.append(indent)
+
+        out_lines.append(line)
+
+    return "\n".join(out_lines)
+
+
+def escape_md_v2(text: str) -> str:
+    """Escape text for Telegram MarkdownV2."""
+    return "".join(f"\\{ch}" if ch in MDV2_SPECIAL_CHARS else ch for ch in text)
+
+
+def escape_md_v2_code(text: str) -> str:
+    """Escape text for Telegram MarkdownV2 code spans/blocks."""
+    return text.replace("\\", "\\\\").replace("`", "\\`")
+
+
+def escape_md_v2_link_url(text: str) -> str:
+    """Escape URL for Telegram MarkdownV2 link destination."""
+    return "".join(f"\\{ch}" if ch in MDV2_LINK_ESCAPE else ch for ch in text)
+
+
+def mdv2_bold(text: str) -> str:
+    """Format text as bold in MarkdownV2."""
+    return f"*{escape_md_v2(text)}*"
+
+
+def mdv2_code_inline(text: str) -> str:
+    """Format text as inline code in MarkdownV2."""
+    return f"`{escape_md_v2_code(text)}`"
+
+
+def format_status(emoji: str, label: str, suffix: str | None = None) -> str:
+    """Format a status message with emoji and optional suffix."""
+    base = f"{emoji} {mdv2_bold(label)}"
+    if suffix:
+        return f"{base} {escape_md_v2(suffix)}"
+    return base
+
+
+def render_markdown_to_mdv2(text: str) -> str:
+    """Render common Markdown into Telegram MarkdownV2."""
+    if not text:
+        return ""
+
+    text = _normalize_gfm_tables(text)
+    tokens = _MD.parse(text)
+
+    def render_inline_table_plain(children) -> str:
+        out: list[str] = []
+        for tok in children:
+            if tok.type == "text" or tok.type == "code_inline":
+                out.append(tok.content)
+            elif tok.type in {"softbreak", "hardbreak"}:
+                out.append(" ")
+            elif tok.type == "image" and tok.content:
+                out.append(tok.content)
+        return "".join(out)
+
+    def render_inline_plain(children) -> str:
+        out: list[str] = []
+        for tok in children:
+            if tok.type == "text" or tok.type == "code_inline":
+                out.append(escape_md_v2(tok.content))
+            elif tok.type in {"softbreak", "hardbreak"}:
+                out.append("\n")
+        return "".join(out)
+
+    def render_inline(children) -> str:
+        out: list[str] = []
+        i = 0
+        while i < len(children):
+            tok = children[i]
+            t = tok.type
+            if t == "text":
+                out.append(escape_md_v2(tok.content))
+            elif t in {"softbreak", "hardbreak"}:
+                out.append("\n")
+            elif t == "em_open" or t == "em_close":
+                out.append("_")
+            elif t == "strong_open" or t == "strong_close":
+                out.append("*")
+            elif t == "s_open" or t == "s_close":
+                out.append("~")
+            elif t == "code_inline":
+                out.append(f"`{escape_md_v2_code(tok.content)}`")
+            elif t == "link_open":
+                href = ""
+                if tok.attrs:
+                    if isinstance(tok.attrs, dict):
+                        href = tok.attrs.get("href", "")
+                    else:
+                        for key, val in tok.attrs:
+                            if key == "href":
+                                href = val
+                                break
+                inner_tokens = []
+                i += 1
+                while i < len(children) and children[i].type != "link_close":
+                    inner_tokens.append(children[i])
+                    i += 1
+                link_text = ""
+                for child in inner_tokens:
+                    if child.type == "text" or child.type == "code_inline":
+                        link_text += child.content
+                out.append(
+                    f"[{escape_md_v2(link_text)}]({escape_md_v2_link_url(href)})"
+                )
+            elif t == "image":
+                href = ""
+                alt = tok.content or ""
+                if tok.attrs:
+                    if isinstance(tok.attrs, dict):
+                        href = tok.attrs.get("src", "")
+                    else:
+                        for key, val in tok.attrs:
+                            if key == "src":
+                                href = val
+                                break
+                if alt:
+                    out.append(f"{escape_md_v2(alt)} ({escape_md_v2_link_url(href)})")
+                else:
+                    out.append(escape_md_v2_link_url(href))
+            else:
+                out.append(escape_md_v2(tok.content or ""))
+            i += 1
+        return "".join(out)
+
+    out: list[str] = []
+    list_stack: list[dict] = []
+    pending_prefix: str | None = None
+    blockquote_level = 0
+    in_heading = False
+
+    def apply_blockquote(val: str) -> str:
+        if blockquote_level <= 0:
+            return val
+        prefix = "> " * blockquote_level
+        return prefix + val.replace("\n", "\n" + prefix)
+
+    i = 0
+    while i < len(tokens):
+        tok = tokens[i]
+        t = tok.type
+        if t == "paragraph_open":
+            pass
+        elif t == "paragraph_close":
+            out.append("\n")
+        elif t == "heading_open":
+            in_heading = True
+        elif t == "heading_close":
+            in_heading = False
+            out.append("\n")
+        elif t == "bullet_list_open":
+            list_stack.append({"type": "bullet", "index": 1})
+        elif t == "bullet_list_close":
+            if list_stack:
+                list_stack.pop()
+            out.append("\n")
+        elif t == "ordered_list_open":
+            start = 1
+            if tok.attrs:
+                if isinstance(tok.attrs, dict):
+                    val = tok.attrs.get("start")
+                    if val is not None:
+                        try:
+                            start = int(val)
+                        except TypeError, ValueError:
+                            start = 1
+                else:
+                    for key, val in tok.attrs:
+                        if key == "start":
+                            try:
+                                start = int(val)
+                            except TypeError, ValueError:
+                                start = 1
+                            break
+            list_stack.append({"type": "ordered", "index": start})
+        elif t == "ordered_list_close":
+            if list_stack:
+                list_stack.pop()
+            out.append("\n")
+        elif t == "list_item_open":
+            if list_stack:
+                top = list_stack[-1]
+                if top["type"] == "bullet":
+                    pending_prefix = "\\- "
+                else:
+                    pending_prefix = f"{top['index']}\\."
+                    top["index"] += 1
+                    pending_prefix += " "
+        elif t == "list_item_close":
+            out.append("\n")
+        elif t == "blockquote_open":
+            blockquote_level += 1
+        elif t == "blockquote_close":
+            blockquote_level = max(0, blockquote_level - 1)
+            out.append("\n")
+        elif t == "table_open":
+            if pending_prefix:
+                out.append(apply_blockquote(pending_prefix.rstrip()))
+                out.append("\n")
+                pending_prefix = None
+
+            rows: list[list[str]] = []
+            row_is_header: list[bool] = []
+
+            j = i + 1
+            in_thead = False
+            in_row = False
+            current_row: list[str] = []
+            current_row_header = False
+
+            in_cell = False
+            cell_parts: list[str] = []
+
+            while j < len(tokens):
+                tt = tokens[j].type
+                if tt == "thead_open":
+                    in_thead = True
+                elif tt == "thead_close":
+                    in_thead = False
+                elif tt == "tr_open":
+                    in_row = True
+                    current_row = []
+                    current_row_header = in_thead
+                elif tt in {"th_open", "td_open"}:
+                    in_cell = True
+                    cell_parts = []
+                elif tt == "inline" and in_cell:
+                    cell_parts.append(
+                        render_inline_table_plain(tokens[j].children or [])
+                    )
+                elif tt in {"th_close", "td_close"} and in_cell:
+                    cell = " ".join(cell_parts).strip()
+                    current_row.append(cell)
+                    in_cell = False
+                    cell_parts = []
+                elif tt == "tr_close" and in_row:
+                    rows.append(current_row)
+                    row_is_header.append(bool(current_row_header))
+                    in_row = False
+                elif tt == "table_close":
+                    break
+                j += 1
+
+            if rows:
+                col_count = max((len(r) for r in rows), default=0)
+                norm_rows: list[list[str]] = []
+                for r in rows:
+                    if len(r) < col_count:
+                        r = r + [""] * (col_count - len(r))
+                    norm_rows.append(r)
+
+                widths: list[int] = []
+                for c in range(col_count):
+                    w = max((len(r[c]) for r in norm_rows), default=0)
+                    widths.append(max(w, 3))
+
+                def fmt_row(
+                    r: list[str], _w: list[int] = widths, _c: int = col_count
+                ) -> str:
+                    cells = [r[c].ljust(_w[c]) for c in range(_c)]
+                    return "| " + " | ".join(cells) + " |"
+
+                def fmt_sep(_w: list[int] = widths, _c: int = col_count) -> str:
+                    cells = ["-" * _w[c] for c in range(_c)]
+                    return "| " + " | ".join(cells) + " |"
+
+                last_header_idx = -1
+                for idx, is_h in enumerate(row_is_header):
+                    if is_h:
+                        last_header_idx = idx
+
+                lines: list[str] = []
+                for idx, r in enumerate(norm_rows):
+                    lines.append(fmt_row(r))
+                    if idx == last_header_idx:
+                        lines.append(fmt_sep())
+
+                table_text = "\n".join(lines).rstrip()
+                out.append(f"```\n{escape_md_v2_code(table_text)}\n```")
+                out.append("\n")
+
+            i = j + 1
+            continue
+        elif t in {"code_block", "fence"}:
+            code = escape_md_v2_code(tok.content.rstrip("\n"))
+            out.append(f"```\n{code}\n```")
+            out.append("\n")
+        elif t == "inline":
+            rendered = render_inline(tok.children or [])
+            if in_heading:
+                rendered = f"*{render_inline_plain(tok.children or [])}*"
+            if pending_prefix:
+                rendered = pending_prefix + rendered
+                pending_prefix = None
+            rendered = apply_blockquote(rendered)
+            out.append(rendered)
+        else:
+            if tok.content:
+                out.append(escape_md_v2(tok.content))
+        i += 1
+
+    return "".join(out).rstrip()
+
+
+__all__ = [
+    "escape_md_v2",
+    "escape_md_v2_code",
+    "escape_md_v2_link_url",
+    "format_status",
+    "mdv2_bold",
+    "mdv2_code_inline",
+    "render_markdown_to_mdv2",
+]

Claude_Code/messaging/session.py

@@ -0,0 +1,289 @@
+"""
+Session Store for Messaging Platforms
+
+Provides persistent storage for mapping platform messages to Claude CLI session IDs
+and message trees for conversation continuation.
+"""
+
+import json
+import os
+import threading
+from datetime import UTC, datetime
+from typing import Any
+
+from loguru import logger
+
+
+class SessionStore:
+    """
+    Persistent storage for message ↔ Claude session mappings and message trees.
+
+    Uses a JSON file for storage with thread-safe operations.
+    Platform-agnostic: works with any messaging platform.
+    """
+
+    def __init__(self, storage_path: str = "sessions.json"):
+        self.storage_path = storage_path
+        self._lock = threading.Lock()
+        self._trees: dict[str, dict] = {}  # root_id -> tree data
+        self._node_to_tree: dict[str, str] = {}  # node_id -> root_id
+        # Per-chat message ID log used to support best-effort UI clearing (/clear).
+        # Key: "{platform}:{chat_id}" -> list of records
+        self._message_log: dict[str, list[dict[str, Any]]] = {}
+        self._message_log_ids: dict[str, set[str]] = {}
+        self._dirty = False
+        self._save_timer: threading.Timer | None = None
+        self._save_debounce_secs = 0.5
+        cap_raw = os.getenv("MAX_MESSAGE_LOG_ENTRIES_PER_CHAT", "").strip()
+        try:
+            self._message_log_cap: int | None = int(cap_raw) if cap_raw else None
+        except ValueError:
+            self._message_log_cap = None
+        self._load()
+
+    def _make_chat_key(self, platform: str, chat_id: str) -> str:
+        return f"{platform}:{chat_id}"
+
+    def _load(self) -> None:
+        """Load sessions and trees from disk."""
+        if not os.path.exists(self.storage_path):
+            return
+
+        try:
+            with open(self.storage_path, encoding="utf-8") as f:
+                data = json.load(f)
+
+            # Load trees
+            self._trees = data.get("trees", {})
+            self._node_to_tree = data.get("node_to_tree", {})
+
+            # Load message log (optional/backward compatible)
+            raw_log = data.get("message_log", {}) or {}
+            if isinstance(raw_log, dict):
+                self._message_log = {}
+                self._message_log_ids = {}
+                for chat_key, items in raw_log.items():
+                    if not isinstance(chat_key, str) or not isinstance(items, list):
+                        continue
+                    cleaned: list[dict[str, Any]] = []
+                    seen: set[str] = set()
+                    for it in items:
+                        if not isinstance(it, dict):
+                            continue
+                        mid = it.get("message_id")
+                        if mid is None:
+                            continue
+                        mid_s = str(mid)
+                        if mid_s in seen:
+                            continue
+                        seen.add(mid_s)
+                        cleaned.append(
+                            {
+                                "message_id": mid_s,
+                                "ts": str(it.get("ts") or ""),
+                                "direction": str(it.get("direction") or ""),
+                                "kind": str(it.get("kind") or ""),
+                            }
+                        )
+                    self._message_log[chat_key] = cleaned
+                    self._message_log_ids[chat_key] = seen
+
+            logger.info(
+                f"Loaded {len(self._trees)} trees and "
+                f"{sum(len(v) for v in self._message_log.values())} msg_ids from {self.storage_path}"
+            )
+        except Exception as e:
+            logger.error(f"Failed to load sessions: {e}")
+
+    def _snapshot(self) -> dict:
+        """Snapshot current state for serialization. Caller must hold self._lock."""
+        return {
+            "trees": dict(self._trees),
+            "node_to_tree": dict(self._node_to_tree),
+            "message_log": {k: list(v) for k, v in self._message_log.items()},
+        }
+
+    def _write_data(self, data: dict) -> None:
+        """Write data dict to disk. Must be called WITHOUT holding self._lock."""
+        with open(self.storage_path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+
+    def _schedule_save(self) -> None:
+        """Schedule a debounced save. Caller must hold self._lock."""
+        self._dirty = True
+        if self._save_timer is not None:
+            self._save_timer.cancel()
+            self._save_timer = None
+        self._save_timer = threading.Timer(
+            self._save_debounce_secs, self._save_from_timer
+        )
+        self._save_timer.daemon = True
+        self._save_timer.start()
+
+    def _save_from_timer(self) -> None:
+        """Timer callback: save if dirty. Runs in timer thread."""
+        with self._lock:
+            if not self._dirty:
+                self._save_timer = None
+                return
+            snapshot = self._snapshot()
+            self._dirty = False
+            self._save_timer = None
+        try:
+            self._write_data(snapshot)
+        except Exception as e:
+            logger.error(f"Failed to save sessions: {e}")
+            with self._lock:
+                self._dirty = True
+
+    def _flush_save(self) -> dict:
+        """Cancel pending timer and snapshot current state. Caller must hold self._lock.
+        Returns snapshot dict; caller must call _write_data(snapshot) outside the lock."""
+        if self._save_timer is not None:
+            self._save_timer.cancel()
+            self._save_timer = None
+        self._dirty = False
+        return self._snapshot()
+
+    def flush_pending_save(self) -> None:
+        """Flush any pending debounced save. Call on shutdown to avoid losing data."""
+        with self._lock:
+            snapshot = self._flush_save()
+        try:
+            self._write_data(snapshot)
+        except Exception as e:
+            logger.error(f"Failed to save sessions: {e}")
+            with self._lock:
+                self._dirty = True
+
+    def record_message_id(
+        self,
+        platform: str,
+        chat_id: str,
+        message_id: str,
+        direction: str,
+        kind: str,
+    ) -> None:
+        """Record a message_id for later best-effort deletion (/clear)."""
+        if message_id is None:
+            return
+
+        chat_key = self._make_chat_key(str(platform), str(chat_id))
+        mid = str(message_id)
+
+        with self._lock:
+            seen = self._message_log_ids.setdefault(chat_key, set())
+            if mid in seen:
+                return
+
+            rec = {
+                "message_id": mid,
+                "ts": datetime.now(UTC).isoformat(),
+                "direction": str(direction),
+                "kind": str(kind),
+            }
+            self._message_log.setdefault(chat_key, []).append(rec)
+            seen.add(mid)
+
+            # Optional cap to prevent unbounded growth if configured.
+            if self._message_log_cap is not None and self._message_log_cap > 0:
+                items = self._message_log.get(chat_key, [])
+                if len(items) > self._message_log_cap:
+                    self._message_log[chat_key] = items[-self._message_log_cap :]
+                    self._message_log_ids[chat_key] = {
+                        str(x.get("message_id")) for x in self._message_log[chat_key]
+                    }
+
+            self._schedule_save()
+
+    def get_message_ids_for_chat(self, platform: str, chat_id: str) -> list[str]:
+        """Get all recorded message IDs for a chat (in insertion order)."""
+        chat_key = self._make_chat_key(str(platform), str(chat_id))
+        with self._lock:
+            items = self._message_log.get(chat_key, [])
+            return [
+                str(x.get("message_id"))
+                for x in items
+                if x.get("message_id") is not None
+            ]
+
+    def clear_all(self) -> None:
+        """Clear all stored sessions/trees/mappings and persist an empty store."""
+        with self._lock:
+            self._trees.clear()
+            self._node_to_tree.clear()
+            self._message_log.clear()
+            self._message_log_ids.clear()
+            snapshot = self._flush_save()
+        try:
+            self._write_data(snapshot)
+        except Exception as e:
+            logger.error(f"Failed to save sessions: {e}")
+            with self._lock:
+                self._dirty = True
+
+    # ==================== Tree Methods ====================
+
+    def save_tree(self, root_id: str, tree_data: dict) -> None:
+        """
+        Save a message tree.
+
+        Args:
+            root_id: Root node ID of the tree
+            tree_data: Serialized tree data from tree.to_dict()
+        """
+        with self._lock:
+            self._trees[root_id] = tree_data
+
+            # Update node-to-tree mapping
+            for node_id in tree_data.get("nodes", {}):
+                self._node_to_tree[node_id] = root_id
+
+            self._schedule_save()
+            logger.debug(f"Saved tree {root_id}")
+
+    def get_tree(self, root_id: str) -> dict | None:
+        """Get a tree by its root ID."""
+        with self._lock:
+            return self._trees.get(root_id)
+
+    def register_node(self, node_id: str, root_id: str) -> None:
+        """Register a node ID to a tree root."""
+        with self._lock:
+            self._node_to_tree[node_id] = root_id
+            self._schedule_save()
+
+    def remove_node_mappings(self, node_ids: list[str]) -> None:
+        """Remove node IDs from the node-to-tree mapping."""
+        with self._lock:
+            for nid in node_ids:
+                self._node_to_tree.pop(nid, None)
+            self._schedule_save()
+
+    def remove_tree(self, root_id: str) -> None:
+        """Remove a tree and all its node mappings from the store."""
+        with self._lock:
+            tree_data = self._trees.pop(root_id, None)
+            if tree_data:
+                for node_id in tree_data.get("nodes", {}):
+                    self._node_to_tree.pop(node_id, None)
+                self._schedule_save()
+
+    def get_all_trees(self) -> dict[str, dict]:
+        """Get all stored trees (public accessor)."""
+        with self._lock:
+            return dict(self._trees)
+
+    def get_node_mapping(self) -> dict[str, str]:
+        """Get the node-to-tree mapping (public accessor)."""
+        with self._lock:
+            return dict(self._node_to_tree)
+
+    def sync_from_tree_data(
+        self, trees: dict[str, dict], node_to_tree: dict[str, str]
+    ) -> None:
+        """Sync internal tree state from external data and persist."""
+        with self._lock:
+            self._trees = trees
+            self._node_to_tree = node_to_tree
+            self._schedule_save()

Claude_Code/messaging/transcript.py

@@ -0,0 +1,577 @@
+"""Ordered transcript builder for messaging UIs (Telegram, etc.).
+
+This module maintains an ordered list of "segments" that represent what the user
+should see in the chat transcript: thinking, tool calls, tool results, subagent
+headers, and assistant text. It is designed for in-place message editing where
+the transcript grows over time and older content must be truncated.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from abc import ABC, abstractmethod
+from collections import deque
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+from typing import Any
+
+from loguru import logger
+
+
+def _safe_json_dumps(obj: Any) -> str:
+    try:
+        return json.dumps(obj, indent=2, ensure_ascii=False, sort_keys=True)
+    except Exception:
+        return str(obj)
+
+
+@dataclass
+class Segment(ABC):
+    kind: str
+
+    @abstractmethod
+    def render(self, ctx: RenderCtx) -> str: ...
+
+
+@dataclass
+class ThinkingSegment(Segment):
+    def __init__(self) -> None:
+        super().__init__(kind="thinking")
+        self._parts: list[str] = []
+
+    def append(self, t: str) -> None:
+        if t:
+            self._parts.append(t)
+
+    @property
+    def text(self) -> str:
+        return "".join(self._parts)
+
+    def render(self, ctx: RenderCtx) -> str:
+        raw = self.text or ""
+        if ctx.thinking_tail_max is not None and len(raw) > ctx.thinking_tail_max:
+            raw = "..." + raw[-(ctx.thinking_tail_max - 3) :]
+        inner = ctx.escape_code(raw)
+        return f"💭 {ctx.bold('Thinking')}\n```\n{inner}\n```"
+
+
+@dataclass
+class TextSegment(Segment):
+    def __init__(self) -> None:
+        super().__init__(kind="text")
+        self._parts: list[str] = []
+
+    def append(self, t: str) -> None:
+        if t:
+            self._parts.append(t)
+
+    @property
+    def text(self) -> str:
+        return "".join(self._parts)
+
+    def render(self, ctx: RenderCtx) -> str:
+        raw = self.text or ""
+        if ctx.text_tail_max is not None and len(raw) > ctx.text_tail_max:
+            raw = "..." + raw[-(ctx.text_tail_max - 3) :]
+        return ctx.render_markdown(raw)
+
+
+@dataclass
+class ToolCallSegment(Segment):
+    tool_use_id: str
+    name: str
+    closed: bool = False
+    indent_level: int = 0
+
+    def __init__(self, tool_use_id: str, name: str, *, indent_level: int = 0) -> None:
+        super().__init__(kind="tool_call")
+        self.tool_use_id = str(tool_use_id or "")
+        self.name = str(name or "tool")
+        self.indent_level = max(0, int(indent_level))
+
+    def render(self, ctx: RenderCtx) -> str:
+        name = ctx.code_inline(self.name)
+        # Per UX requirement: do not display tool args/results, only the tool call.
+        prefix = "  " * self.indent_level
+        return f"{prefix}🛠 {ctx.bold('Tool call:')} {name}"
+
+
+@dataclass
+class ToolResultSegment(Segment):
+    tool_use_id: str
+    name: str | None
+    content_text: str
+    is_error: bool = False
+
+    def __init__(
+        self,
+        tool_use_id: str,
+        content: Any,
+        *,
+        name: str | None = None,
+        is_error: bool = False,
+    ) -> None:
+        super().__init__(kind="tool_result")
+        self.tool_use_id = str(tool_use_id or "")
+        self.name = str(name) if name is not None else None
+        self.is_error = bool(is_error)
+        if isinstance(content, str):
+            self.content_text = content
+        else:
+            self.content_text = _safe_json_dumps(content)
+
+    def render(self, ctx: RenderCtx) -> str:
+        raw = self.content_text or ""
+        if ctx.tool_output_tail_max is not None and len(raw) > ctx.tool_output_tail_max:
+            raw = "..." + raw[-(ctx.tool_output_tail_max - 3) :]
+        inner = ctx.escape_code(raw)
+        label = "Tool error:" if self.is_error else "Tool result:"
+        maybe_name = f" {ctx.code_inline(self.name)}" if self.name else ""
+        return f"📤 {ctx.bold(label)}{maybe_name}\n```\n{inner}\n```"
+
+
+@dataclass
+class SubagentSegment(Segment):
+    description: str
+    tool_calls: int = 0
+    tools_used: set[str] = field(default_factory=set)
+    current_tool: ToolCallSegment | None = None
+
+    def __init__(self, description: str) -> None:
+        super().__init__(kind="subagent")
+        self.description = str(description or "Subagent")
+        self.tool_calls = 0
+        self.tools_used = set()
+        self.current_tool = None
+
+    def set_current_tool_call(self, tool_use_id: str, name: str) -> ToolCallSegment:
+        tool_use_id = str(tool_use_id or "")
+        name = str(name or "tool")
+        self.tools_used.add(name)
+        self.tool_calls += 1
+        self.current_tool = ToolCallSegment(tool_use_id, name, indent_level=1)
+        return self.current_tool
+
+    def render(self, ctx: RenderCtx) -> str:
+        inner_prefix = "  "
+
+        lines: list[str] = [
+            f"🤖 {ctx.bold('Subagent:')} {ctx.code_inline(self.description)}"
+        ]
+
+        if self.current_tool is not None:
+            try:
+                rendered = self.current_tool.render(ctx)
+            except Exception:
+                rendered = ""
+            if rendered:
+                lines.append(rendered)
+
+        tools_used = sorted(self.tools_used)
+        tools_set_raw = "{{{}}}".format(", ".join(tools_used)) if tools_used else "{}"
+
+        # Keep braces inside a code entity so MarkdownV2 doesn't require escaping them.
+        lines.append(
+            f"{inner_prefix}{ctx.bold('Tools used:')} {ctx.code_inline(tools_set_raw)}"
+        )
+        lines.append(
+            f"{inner_prefix}{ctx.bold('Tool calls:')} {ctx.code_inline(str(self.tool_calls))}"
+        )
+        return "\n".join(lines)
+
+
+@dataclass
+class ErrorSegment(Segment):
+    message: str
+
+    def __init__(self, message: str) -> None:
+        super().__init__(kind="error")
+        self.message = str(message or "Unknown error")
+
+    def render(self, ctx: RenderCtx) -> str:
+        return f"⚠️ {ctx.bold('Error:')} {ctx.code_inline(self.message)}"
+
+
+@dataclass
+class RenderCtx:
+    bold: Callable[[str], str]
+    code_inline: Callable[[str], str]
+    escape_code: Callable[[str], str]
+    escape_text: Callable[[str], str]
+    render_markdown: Callable[[str], str]
+
+    thinking_tail_max: int | None = 1000
+    tool_input_tail_max: int | None = 1200
+    tool_output_tail_max: int | None = 1600
+    text_tail_max: int | None = 2000
+
+
+class TranscriptBuffer:
+    """Maintains an ordered, truncatable transcript of events."""
+
+    def __init__(self, *, show_tool_results: bool = True) -> None:
+        self._segments: list[Segment] = []
+        self._open_thinking_by_index: dict[int, ThinkingSegment] = {}
+        self._open_text_by_index: dict[int, TextSegment] = {}
+
+        # content_block index -> tool call segment (for streaming tool args)
+        self._open_tools_by_index: dict[int, ToolCallSegment] = {}
+
+        # tool_use_id -> tool name (for tool_result labeling)
+        self._tool_name_by_id: dict[str, str] = {}
+
+        self._show_tool_results = bool(show_tool_results)
+
+        # subagent context stack. Each entry is the Task tool_use_id we are waiting to close.
+        self._subagent_stack: list[str] = []
+        # Parallel stack of segments for rendering nested subagents.
+        self._subagent_segments: list[SubagentSegment] = []
+        self._debug_subagent_stack = os.getenv("DEBUG_SUBAGENT_STACK") == "1"
+
+    def _in_subagent(self) -> bool:
+        return bool(self._subagent_stack)
+
+    def _subagent_current(self) -> SubagentSegment | None:
+        return self._subagent_segments[-1] if self._subagent_segments else None
+
+    def _task_heading_from_input(self, inp: Any) -> str:
+        # We never display full JSON args; only extract a short heading.
+        if isinstance(inp, dict):
+            desc = str(inp.get("description", "") or "").strip()
+            if desc:
+                return desc
+            subagent_type = str(inp.get("subagent_type", "") or "").strip()
+            if subagent_type:
+                return subagent_type
+            typ = str(inp.get("type", "") or "").strip()
+            if typ:
+                return typ
+        return "Subagent"
+
+    def _subagent_push(self, tool_id: str, seg: SubagentSegment) -> None:
+        # Some providers can omit ids; still track depth for UI suppression.
+        tool_id = (
+            str(tool_id or "").strip() or f"__task_{len(self._subagent_stack) + 1}"
+        )
+        self._subagent_stack.append(tool_id)
+        self._subagent_segments.append(seg)
+        if self._debug_subagent_stack:
+            logger.debug(
+                "SUBAGENT_STACK: push id=%r depth=%d heading=%r",
+                tool_id,
+                len(self._subagent_stack),
+                getattr(seg, "description", None),
+            )
+
+    def _subagent_pop(self, tool_id: str) -> bool:
+        tool_id = str(tool_id or "").strip()
+        if not self._subagent_stack:
+            return False
+
+        def _ids_roughly_match(stack_id: str, result_id: str) -> bool:
+            if not stack_id or not result_id:
+                return False
+            if stack_id == result_id:
+                return True
+            # Some providers emit Task result ids with a suffix/prefix variant.
+            # Treat those as the same logical Task invocation.
+            return stack_id.startswith(result_id) or result_id.startswith(stack_id)
+
+        if tool_id:
+            # O(1) common case: LIFO - top of stack matches.
+            if _ids_roughly_match(self._subagent_stack[-1], tool_id):
+                self._subagent_stack.pop()
+                if self._subagent_segments:
+                    self._subagent_segments.pop()
+                if self._debug_subagent_stack:
+                    logger.debug(
+                        "SUBAGENT_STACK: pop id=%r depth=%d (LIFO)",
+                        tool_id,
+                        len(self._subagent_stack),
+                    )
+                return True
+            # Pop to the matching id (defensive against non-LIFO emissions).
+            idx = -1
+            for i in range(len(self._subagent_stack) - 1, -1, -1):
+                if _ids_roughly_match(self._subagent_stack[i], tool_id):
+                    idx = i
+                    break
+            if idx < 0:
+                return False
+            while len(self._subagent_stack) > idx:
+                popped = self._subagent_stack.pop()
+                if self._subagent_segments:
+                    self._subagent_segments.pop()
+                if self._debug_subagent_stack:
+                    logger.debug(
+                        "SUBAGENT_STACK: pop id=%r depth=%d (matched=%r)",
+                        popped,
+                        len(self._subagent_stack),
+                        tool_id,
+                    )
+            return True
+
+        # No id in result; only close if we have a synthetic top marker.
+        if self._subagent_stack and self._subagent_stack[-1].startswith("__task_"):
+            popped = self._subagent_stack.pop()
+            if self._subagent_segments:
+                self._subagent_segments.pop()
+            if self._debug_subagent_stack:
+                logger.debug(
+                    "SUBAGENT_STACK: pop id=%r depth=%d (synthetic)",
+                    popped,
+                    len(self._subagent_stack),
+                )
+            return True
+        return False
+
+    def _ensure_thinking(self) -> ThinkingSegment:
+        seg = ThinkingSegment()
+        self._segments.append(seg)
+        return seg
+
+    def _ensure_text(self) -> TextSegment:
+        seg = TextSegment()
+        self._segments.append(seg)
+        return seg
+
+    def apply(self, ev: dict[str, Any]) -> None:
+        """Apply a parsed event to the transcript."""
+        et = ev.get("type")
+
+        # Subagent rules: inside a Task/subagent, we only show tool calls/results.
+        if self._in_subagent() and et in (
+            "thinking_start",
+            "thinking_delta",
+            "thinking_chunk",
+            "text_start",
+            "text_delta",
+            "text_chunk",
+        ):
+            return
+
+        if et == "thinking_start":
+            idx = int(ev.get("index", -1))
+            if idx >= 0:
+                # Defensive: if a provider reuses indices without emitting a stop,
+                # close the previous open segment first.
+                self.apply({"type": "block_stop", "index": idx})
+            seg = self._ensure_thinking()
+            if idx >= 0:
+                self._open_thinking_by_index[idx] = seg
+            return
+        if et in ("thinking_delta", "thinking_chunk"):
+            idx = int(ev.get("index", -1))
+            seg = self._open_thinking_by_index.get(idx)
+            if seg is None:
+                seg = self._ensure_thinking()
+                if idx >= 0:
+                    self._open_thinking_by_index[idx] = seg
+            seg.append(str(ev.get("text", "")))
+            return
+        if et == "thinking_stop":
+            idx = int(ev.get("index", -1))
+            if idx >= 0:
+                self._open_thinking_by_index.pop(idx, None)
+            return
+
+        if et == "text_start":
+            idx = int(ev.get("index", -1))
+            if idx >= 0:
+                self.apply({"type": "block_stop", "index": idx})
+            seg = self._ensure_text()
+            if idx >= 0:
+                self._open_text_by_index[idx] = seg
+            return
+        if et in ("text_delta", "text_chunk"):
+            idx = int(ev.get("index", -1))
+            seg = self._open_text_by_index.get(idx)
+            if seg is None:
+                seg = self._ensure_text()
+                if idx >= 0:
+                    self._open_text_by_index[idx] = seg
+            seg.append(str(ev.get("text", "")))
+            return
+        if et == "text_stop":
+            idx = int(ev.get("index", -1))
+            if idx >= 0:
+                self._open_text_by_index.pop(idx, None)
+            return
+
+        if et == "tool_use_start":
+            idx = int(ev.get("index", -1))
+            if idx >= 0:
+                self.apply({"type": "block_stop", "index": idx})
+            tool_id = str(ev.get("id", "") or "").strip()
+            name = str(ev.get("name", "") or "tool")
+            if tool_id:
+                self._tool_name_by_id[tool_id] = name
+
+            # Task tool indicates subagent.
+            if name == "Task":
+                heading = self._task_heading_from_input(ev.get("input"))
+                seg = SubagentSegment(heading)
+                self._segments.append(seg)
+                self._subagent_push(tool_id, seg)
+                return
+
+            # Normal tool call.
+            if self._in_subagent():
+                parent = self._subagent_current()
+                if parent is not None:
+                    seg = parent.set_current_tool_call(tool_id, name)
+                else:
+                    seg = ToolCallSegment(tool_id, name)
+                    self._segments.append(seg)
+            else:
+                seg = ToolCallSegment(tool_id, name)
+                self._segments.append(seg)
+
+            if idx >= 0:
+                self._open_tools_by_index[idx] = seg
+            return
+
+        if et == "tool_use_delta":
+            # Track open tool by index for tool_use_stop (closing state).
+            return
+
+        if et == "tool_use_stop":
+            idx = int(ev.get("index", -1))
+            seg = self._open_tools_by_index.pop(idx, None)
+            if seg is not None:
+                seg.closed = True
+            return
+
+        if et == "block_stop":
+            idx = int(ev.get("index", -1))
+            if idx in self._open_tools_by_index:
+                self.apply({"type": "tool_use_stop", "index": idx})
+                return
+            if idx in self._open_thinking_by_index:
+                self.apply({"type": "thinking_stop", "index": idx})
+                return
+            if idx in self._open_text_by_index:
+                self.apply({"type": "text_stop", "index": idx})
+                return
+            return
+
+        if et == "tool_use":
+            tool_id = str(ev.get("id", "") or "").strip()
+            name = str(ev.get("name", "") or "tool")
+            if tool_id:
+                self._tool_name_by_id[tool_id] = name
+
+            if name == "Task":
+                heading = self._task_heading_from_input(ev.get("input"))
+                seg = SubagentSegment(heading)
+                self._segments.append(seg)
+                self._subagent_push(tool_id, seg)
+                return
+
+            if self._in_subagent():
+                parent = self._subagent_current()
+                if parent is not None:
+                    seg = parent.set_current_tool_call(tool_id, name)
+                else:
+                    seg = ToolCallSegment(tool_id, name)
+                    self._segments.append(seg)
+            else:
+                seg = ToolCallSegment(tool_id, name)
+                self._segments.append(seg)
+
+            seg.closed = True
+            return
+
+        if et == "tool_result":
+            tool_id = str(ev.get("tool_use_id", "") or "").strip()
+            name = self._tool_name_by_id.get(tool_id)
+
+            # If this was the Task tool result, close subagent context.
+            if self._subagent_stack:
+                popped = self._subagent_pop(tool_id)
+                top = self._subagent_stack[-1] if self._subagent_stack else ""
+                looks_like_task_id = "task" in tool_id.lower()
+                # Some streams omit Task tool_use ids (synthetic stack ids), but include
+                # a real Task id on tool_result (e.g. "functions.Task:0"). Reconcile that.
+                if (
+                    not popped
+                    and tool_id
+                    and top.startswith("__task_")
+                    and (name in (None, "Task"))
+                    and looks_like_task_id
+                ):
+                    self._subagent_pop("")
+
+            if not self._show_tool_results:
+                return
+
+            seg = ToolResultSegment(
+                tool_id,
+                ev.get("content"),
+                name=name,
+                is_error=bool(ev.get("is_error", False)),
+            )
+            self._segments.append(seg)
+            return
+
+        if et == "error":
+            self._segments.append(ErrorSegment(str(ev.get("message", ""))))
+            return
+
+    def render(self, ctx: RenderCtx, *, limit_chars: int, status: str | None) -> str:
+        """Render transcript with truncation (drop oldest segments)."""
+        # Filter out empty rendered segments.
+        rendered: list[str] = []
+        for seg in self._segments:
+            try:
+                out = seg.render(ctx)
+            except Exception:
+                continue
+            if out:
+                rendered.append(out)
+
+        status_text = f"\n\n{status}" if status else ""
+        prefix_marker = ctx.escape_text("... (truncated)\n")
+
+        def _join(parts: Iterable[str], add_marker: bool) -> str:
+            body = "\n".join(parts)
+            if add_marker and body:
+                body = prefix_marker + body
+            return body + status_text if (body or status_text) else status_text
+
+        # Fast path.
+        candidate = _join(rendered, add_marker=False)
+        if len(candidate) <= limit_chars:
+            return candidate
+
+        # Drop oldest segments until under limit (keep the tail).
+        # Use deque for O(1) popleft; list.pop(0) would be O(n) per iteration.
+        parts: deque[str] = deque(rendered)
+        dropped = False
+        last_part: str | None = None
+        while parts:
+            candidate = _join(parts, add_marker=True)
+            if len(candidate) <= limit_chars:
+                return candidate
+            last_part = parts.popleft()
+            dropped = True
+
+        # Nothing fits - preserve tail of last segment instead of only marker+status.
+        if dropped and last_part:
+            budget = limit_chars - len(prefix_marker) - len(status_text)
+            if budget > 20:
+                if len(last_part) > budget:
+                    tail = "..." + last_part[-(budget - 3) :]
+                else:
+                    tail = last_part
+                candidate = prefix_marker + tail + status_text
+                if len(candidate) <= limit_chars:
+                    return candidate
+
+        # Fallback: marker + status only.
+        if dropped:
+            minimal = prefix_marker + status_text.lstrip("\n")
+            if len(minimal) <= limit_chars:
+                return minimal
+        return status or ""

Claude_Code/messaging/transcription.py

@@ -0,0 +1,228 @@
+"""Voice note transcription for messaging platforms.
+
+Supports:
+- Local Whisper (cpu/cuda): Hugging Face transformers pipeline
+- NVIDIA NIM: NVIDIA NIM Whisper/Parakeet
+"""
+
+import os
+from pathlib import Path
+from typing import Any
+
+from loguru import logger
+
+from config.settings import get_settings
+
+# Max file size in bytes (25 MB)
+MAX_AUDIO_SIZE_BYTES = 25 * 1024 * 1024
+
+# NVIDIA NIM Whisper model mapping: (function_id, language_code)
+_NIM_MODEL_MAP: dict[str, tuple[str, str]] = {
+    "nvidia/parakeet-ctc-0.6b-zh-tw": ("8473f56d-51ef-473c-bb26-efd4f5def2bf", "zh-TW"),
+    "nvidia/parakeet-ctc-0.6b-zh-cn": ("9add5ef7-322e-47e0-ad7a-5653fb8d259b", "zh-CN"),
+    "nvidia/parakeet-ctc-0.6b-es": ("None", "es-US"),
+    "nvidia/parakeet-ctc-0.6b-vi": ("f3dff2bb-99f9-403d-a5f1-f574a757deb0", "vi-VN"),
+    "nvidia/parakeet-ctc-1.1b-asr": ("1598d209-5e27-4d3c-8079-4751568b1081", "en-US"),
+    "nvidia/parakeet-ctc-0.6b-asr": ("d8dd4e9b-fbf5-4fb0-9dba-8cf436c8d965", "en-US"),
+    "nvidia/parakeet-1.1b-rnnt-multilingual-asr": (
+        "71203149-d3b7-4460-8231-1be2543a1fca",
+        "",
+    ),
+    "openai/whisper-large-v3": ("b702f636-f60c-4a3d-a6f4-f3568c13bd7d", "multi"),
+}
+
+# Short model names -> full Hugging Face model IDs (for local Whisper)
+_MODEL_MAP: dict[str, str] = {
+    "tiny": "openai/whisper-tiny",
+    "base": "openai/whisper-base",
+    "small": "openai/whisper-small",
+    "medium": "openai/whisper-medium",
+    "large-v2": "openai/whisper-large-v2",
+    "large-v3": "openai/whisper-large-v3",
+    "large-v3-turbo": "openai/whisper-large-v3-turbo",
+}
+
+# Lazy-loaded pipelines: (model_id, device) -> pipeline
+_pipeline_cache: dict[tuple[str, str], Any] = {}
+
+
+def _resolve_model_id(whisper_model: str) -> str:
+    """Resolve short name to full Hugging Face model ID."""
+    return _MODEL_MAP.get(whisper_model, whisper_model)
+
+
+def _get_pipeline(model_id: str, device: str) -> Any:
+    """Lazy-load transformers Whisper pipeline. Raises ImportError if not installed."""
+    global _pipeline_cache
+    if device not in ("cpu", "cuda"):
+        raise ValueError(f"whisper_device must be 'cpu' or 'cuda', got {device!r}")
+    cache_key = (model_id, device)
+    if cache_key not in _pipeline_cache:
+        try:
+            import torch
+            from transformers import AutoModelForSpeechSeq2Seq, AutoProcessor, pipeline
+
+            token = get_settings().hf_token
+            if token:
+                os.environ["HF_TOKEN"] = token
+
+            use_cuda = device == "cuda" and torch.cuda.is_available()
+            pipe_device = "cuda:0" if use_cuda else "cpu"
+            model_dtype = torch.float16 if use_cuda else torch.float32
+
+            model = AutoModelForSpeechSeq2Seq.from_pretrained(
+                model_id,
+                dtype=model_dtype,
+                low_cpu_mem_usage=True,
+                attn_implementation="sdpa",
+            )
+            model = model.to(pipe_device)
+            processor = AutoProcessor.from_pretrained(model_id)
+
+            pipe = pipeline(
+                "automatic-speech-recognition",
+                model=model,
+                tokenizer=processor.tokenizer,
+                feature_extractor=processor.feature_extractor,
+                device=pipe_device,
+            )
+            _pipeline_cache[cache_key] = pipe
+            logger.debug(
+                f"Loaded Whisper pipeline: model={model_id} device={pipe_device}"
+            )
+        except ImportError as e:
+            raise ImportError(
+                "Local Whisper requires the voice_local extra. Install with: uv sync --extra voice_local"
+            ) from e
+    return _pipeline_cache[cache_key]
+
+
+def transcribe_audio(
+    file_path: Path,
+    mime_type: str,
+    *,
+    whisper_model: str = "base",
+    whisper_device: str = "cpu",
+) -> str:
+    """
+    Transcribe audio file to text.
+
+    Supports:
+    - whisper_device="cpu"/"cuda": local Whisper (requires voice_local extra)
+    - whisper_device="nvidia_nim": NVIDIA NIM Whisper API (requires voice extra)
+
+    Args:
+        file_path: Path to audio file (OGG, MP3, MP4, WAV, M4A supported)
+        mime_type: MIME type of the audio (e.g. "audio/ogg")
+        whisper_model: Model ID or short name (local) or NVIDIA NIM model
+        whisper_device: "cpu" | "cuda" | "nvidia_nim" (defaults to WHISPER_DEVICE env var)
+
+    Returns:
+        Transcribed text
+
+    Raises:
+        FileNotFoundError: If file does not exist
+        ValueError: If file too large
+        ImportError: If voice_local extra not installed (for local Whisper)
+    """
+
+    if not file_path.exists():
+        raise FileNotFoundError(f"Audio file not found: {file_path}")
+
+    size = file_path.stat().st_size
+    if size > MAX_AUDIO_SIZE_BYTES:
+        raise ValueError(
+            f"Audio file too large ({size} bytes). Max {MAX_AUDIO_SIZE_BYTES} bytes."
+        )
+
+    if whisper_device == "nvidia_nim":
+        return _transcribe_nim(file_path, whisper_model)
+    else:
+        return _transcribe_local(file_path, whisper_model, whisper_device)
+
+
+# Whisper expects 16 kHz sample rate
+_WHISPER_SAMPLE_RATE = 16000
+
+
+def _load_audio(file_path: Path) -> dict[str, Any]:
+    """Load audio file to waveform dict. No ffmpeg required."""
+    import librosa
+
+    waveform, sr = librosa.load(str(file_path), sr=_WHISPER_SAMPLE_RATE, mono=True)
+    return {"array": waveform, "sampling_rate": sr}
+
+
+def _transcribe_local(file_path: Path, whisper_model: str, whisper_device: str) -> str:
+    """Transcribe using transformers Whisper pipeline."""
+    model_id = _resolve_model_id(whisper_model)
+    pipe = _get_pipeline(model_id, whisper_device)
+    audio = _load_audio(file_path)
+    result = pipe(audio, generate_kwargs={"language": "en", "task": "transcribe"})
+    text = result.get("text", "") or ""
+    if isinstance(text, list):
+        text = " ".join(text) if text else ""
+    result_text = text.strip()
+    logger.debug(f"Local transcription: {len(result_text)} chars")
+    return result_text or "(no speech detected)"
+
+
+def _transcribe_nim(file_path: Path, model: str) -> str:
+    """Transcribe using NVIDIA NIM Whisper API via Riva gRPC client."""
+    try:
+        import riva.client
+    except ImportError as e:
+        raise ImportError(
+            "NVIDIA NIM transcription requires the voice extra. "
+            "Install with: uv sync --extra voice"
+        ) from e
+
+    settings = get_settings()
+    api_key = settings.nvidia_nim_api_key
+
+    # Look up function ID and language code from model mapping
+    model_config = _NIM_MODEL_MAP.get(model)
+    if not model_config:
+        raise ValueError(
+            f"No NVIDIA NIM config found for model: {model}. "
+            f"Supported models: {', '.join(_NIM_MODEL_MAP.keys())}"
+        )
+    function_id, language_code = model_config
+
+    # Riva server configuration
+    server = "grpc.nvcf.nvidia.com:443"
+
+    # Auth with SSL and metadata
+    auth = riva.client.Auth(
+        use_ssl=True,
+        uri=server,
+        metadata_args=[
+            ["function-id", function_id],
+            ["authorization", f"Bearer {api_key}"],
+        ],
+    )
+
+    asr_service = riva.client.ASRService(auth)
+
+    # Configure recognition - language_code from model config
+    config = riva.client.RecognitionConfig(
+        language_code=language_code,
+        max_alternatives=1,
+        verbatim_transcripts=True,
+    )
+
+    # Read audio file
+    with open(file_path, "rb") as f:
+        data = f.read()
+
+    # Perform offline recognition
+    response = asr_service.offline_recognize(data, config)
+
+    # Extract text from response - use getattr for safe attribute access
+    transcript = ""
+    results = getattr(response, "results", None)
+    if results and results[0].alternatives:
+        transcript = results[0].alternatives[0].transcript
+
+    logger.debug(f"NIM transcription: {len(transcript)} chars")
+    return transcript or "(no speech detected)"

Claude_Code/messaging/trees/__init__.py

@@ -0,0 +1,11 @@
+"""Message tree data structures and queue management."""
+
+from .data import MessageNode, MessageState, MessageTree
+from .queue_manager import TreeQueueManager
+
+__all__ = [
+    "MessageNode",
+    "MessageState",
+    "MessageTree",
+    "TreeQueueManager",
+]

Claude_Code/messaging/trees/data.py

@@ -0,0 +1,482 @@
+"""Tree data structures for message queue.
+
+Contains MessageState, MessageNode, and MessageTree classes.
+"""
+
+import asyncio
+from collections import deque
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+
+from loguru import logger
+
+from ..models import IncomingMessage
+
+
+class _SnapshotQueue:
+    """Queue with snapshot/remove helpers, backed by a deque and a set index."""
+
+    def __init__(self) -> None:
+        self._deque: deque[str] = deque()
+        self._set: set[str] = set()
+
+    async def put(self, item: str) -> None:
+        self._deque.append(item)
+        self._set.add(item)
+
+    def put_nowait(self, item: str) -> None:
+        self._deque.append(item)
+        self._set.add(item)
+
+    def get_nowait(self) -> str:
+        if not self._deque:
+            raise asyncio.QueueEmpty()
+        item = self._deque.popleft()
+        self._set.discard(item)
+        return item
+
+    def qsize(self) -> int:
+        return len(self._deque)
+
+    def get_snapshot(self) -> list[str]:
+        """Return current queue contents in FIFO order (read-only copy)."""
+        return list(self._deque)
+
+    def remove_if_present(self, item: str) -> bool:
+        """Remove item from queue if present (O(1) membership check). Returns True if removed."""
+        if item not in self._set:
+            return False
+        self._set.discard(item)
+        self._deque = deque(x for x in self._deque if x != item)
+        return True
+
+
+class MessageState(Enum):
+    """State of a message node in the tree."""
+
+    PENDING = "pending"  # Queued, waiting to be processed
+    IN_PROGRESS = "in_progress"  # Currently being processed by Claude
+    COMPLETED = "completed"  # Processing finished successfully
+    ERROR = "error"  # Processing failed
+
+
+@dataclass
+class MessageNode:
+    """
+    A node in the message tree.
+
+    Each node represents a single message and tracks:
+    - Its relationship to parent/children
+    - Its processing state
+    - Claude session information
+    """
+
+    node_id: str  # Unique ID (typically message_id)
+    incoming: IncomingMessage  # The original message
+    status_message_id: str  # Bot's status message ID
+    state: MessageState = MessageState.PENDING
+    parent_id: str | None = None  # Parent node ID (None for root)
+    session_id: str | None = None  # Claude session ID (forked from parent)
+    children_ids: list[str] = field(default_factory=list)
+    created_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+    completed_at: datetime | None = None
+    error_message: str | None = None
+    context: Any = None  # Additional context if needed
+
+    def set_context(self, context: Any) -> None:
+        self.context = context
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "node_id": self.node_id,
+            "incoming": {
+                "text": self.incoming.text,
+                "chat_id": self.incoming.chat_id,
+                "user_id": self.incoming.user_id,
+                "message_id": self.incoming.message_id,
+                "platform": self.incoming.platform,
+                "reply_to_message_id": self.incoming.reply_to_message_id,
+                "message_thread_id": self.incoming.message_thread_id,
+                "username": self.incoming.username,
+            },
+            "status_message_id": self.status_message_id,
+            "state": self.state.value,
+            "parent_id": self.parent_id,
+            "session_id": self.session_id,
+            "children_ids": self.children_ids,
+            "created_at": self.created_at.isoformat(),
+            "completed_at": self.completed_at.isoformat()
+            if self.completed_at
+            else None,
+            "error_message": self.error_message,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> MessageNode:
+        """Create from dictionary (JSON deserialization)."""
+        incoming_data = data["incoming"]
+        incoming = IncomingMessage(
+            text=incoming_data["text"],
+            chat_id=incoming_data["chat_id"],
+            user_id=incoming_data["user_id"],
+            message_id=incoming_data["message_id"],
+            platform=incoming_data["platform"],
+            reply_to_message_id=incoming_data.get("reply_to_message_id"),
+            message_thread_id=incoming_data.get("message_thread_id"),
+            username=incoming_data.get("username"),
+        )
+        return cls(
+            node_id=data["node_id"],
+            incoming=incoming,
+            status_message_id=data["status_message_id"],
+            state=MessageState(data["state"]),
+            parent_id=data.get("parent_id"),
+            session_id=data.get("session_id"),
+            children_ids=data.get("children_ids", []),
+            created_at=datetime.fromisoformat(data["created_at"]),
+            completed_at=datetime.fromisoformat(data["completed_at"])
+            if data.get("completed_at")
+            else None,
+            error_message=data.get("error_message"),
+        )
+
+
+class MessageTree:
+    """
+    A tree of message nodes with queue functionality.
+
+    Provides:
+    - O(1) node lookup via hashmap
+    - Per-tree message queue
+    - Thread-safe operations via asyncio.Lock
+    """
+
+    def __init__(self, root_node: MessageNode):
+        """
+        Initialize tree with a root node.
+
+        Args:
+            root_node: The root message node
+        """
+        self.root_id = root_node.node_id
+        self._nodes: dict[str, MessageNode] = {root_node.node_id: root_node}
+        self._status_to_node: dict[str, str] = {
+            root_node.status_message_id: root_node.node_id
+        }
+        self._queue: _SnapshotQueue = _SnapshotQueue()
+        self._lock = asyncio.Lock()
+        self._is_processing = False
+        self._current_node_id: str | None = None
+        self._current_task: asyncio.Task | None = None
+
+        logger.debug(f"Created MessageTree with root {self.root_id}")
+
+    def set_current_task(self, task: asyncio.Task | None) -> None:
+        """Set the current processing task. Caller must hold lock."""
+        self._current_task = task
+
+    @property
+    def is_processing(self) -> bool:
+        """Check if tree is currently processing a message."""
+        return self._is_processing
+
+    async def add_node(
+        self,
+        node_id: str,
+        incoming: IncomingMessage,
+        status_message_id: str,
+        parent_id: str,
+    ) -> MessageNode:
+        """
+        Add a child node to the tree.
+
+        Args:
+            node_id: Unique ID for the new node
+            incoming: The incoming message
+            status_message_id: Bot's status message ID
+            parent_id: Parent node ID
+
+        Returns:
+            The created MessageNode
+        """
+        async with self._lock:
+            if parent_id not in self._nodes:
+                raise ValueError(f"Parent node {parent_id} not found in tree")
+
+            node = MessageNode(
+                node_id=node_id,
+                incoming=incoming,
+                status_message_id=status_message_id,
+                parent_id=parent_id,
+                state=MessageState.PENDING,
+            )
+
+            self._nodes[node_id] = node
+            self._status_to_node[status_message_id] = node_id
+            self._nodes[parent_id].children_ids.append(node_id)
+
+            logger.debug(f"Added node {node_id} as child of {parent_id}")
+            return node
+
+    def get_node(self, node_id: str) -> MessageNode | None:
+        """Get a node by ID (O(1) lookup)."""
+        return self._nodes.get(node_id)
+
+    def get_root(self) -> MessageNode:
+        """Get the root node."""
+        return self._nodes[self.root_id]
+
+    def get_children(self, node_id: str) -> list[MessageNode]:
+        """Get all child nodes of a given node."""
+        node = self._nodes.get(node_id)
+        if not node:
+            return []
+        return [self._nodes[cid] for cid in node.children_ids if cid in self._nodes]
+
+    def get_parent(self, node_id: str) -> MessageNode | None:
+        """Get the parent node."""
+        node = self._nodes.get(node_id)
+        if not node or not node.parent_id:
+            return None
+        return self._nodes.get(node.parent_id)
+
+    def get_parent_session_id(self, node_id: str) -> str | None:
+        """
+        Get the parent's session ID for forking.
+
+        Returns None for root nodes.
+        """
+        parent = self.get_parent(node_id)
+        return parent.session_id if parent else None
+
+    async def update_state(
+        self,
+        node_id: str,
+        state: MessageState,
+        session_id: str | None = None,
+        error_message: str | None = None,
+    ) -> None:
+        """Update a node's state."""
+        async with self._lock:
+            node = self._nodes.get(node_id)
+            if not node:
+                logger.warning(f"Node {node_id} not found for state update")
+                return
+
+            node.state = state
+            if session_id:
+                node.session_id = session_id
+            if error_message:
+                node.error_message = error_message
+            if state in (MessageState.COMPLETED, MessageState.ERROR):
+                node.completed_at = datetime.now(UTC)
+
+            logger.debug(f"Node {node_id} state -> {state.value}")
+
+    async def enqueue(self, node_id: str) -> int:
+        """
+        Add a node to the processing queue.
+
+        Returns:
+            Queue position (1-indexed)
+        """
+        async with self._lock:
+            await self._queue.put(node_id)
+            position = self._queue.qsize()
+            logger.debug(f"Enqueued node {node_id}, position {position}")
+            return position
+
+    async def dequeue(self) -> str | None:
+        """
+        Get the next node ID from the queue.
+
+        Returns None if queue is empty.
+        """
+        try:
+            return self._queue.get_nowait()
+        except asyncio.QueueEmpty:
+            return None
+
+    async def get_queue_snapshot(self) -> list[str]:
+        """
+        Get a snapshot of the current queue order.
+
+        Returns:
+            List of node IDs in FIFO order.
+        """
+        async with self._lock:
+            return self._queue.get_snapshot()
+
+    def get_queue_size(self) -> int:
+        """Get number of messages waiting in queue."""
+        return self._queue.qsize()
+
+    def remove_from_queue(self, node_id: str) -> bool:
+        """
+        Remove node_id from the internal queue if present.
+
+        Caller must hold the tree lock (e.g. via with_lock).
+        Returns True if node was removed, False if not in queue.
+        """
+        return self._queue.remove_if_present(node_id)
+
+    @asynccontextmanager
+    async def with_lock(self):
+        """Async context manager for tree lock. Use when multiple operations need atomicity."""
+        async with self._lock:
+            yield
+
+    def set_processing_state(self, node_id: str | None, is_processing: bool) -> None:
+        """Set processing state. Caller must hold lock for consistency with queue operations."""
+        self._is_processing = is_processing
+        self._current_node_id = node_id if is_processing else None
+
+    def clear_current_node(self) -> None:
+        """Clear the currently processing node ID. Caller must hold lock."""
+        self._current_node_id = None
+
+    def is_current_node(self, node_id: str) -> bool:
+        """Check if node_id is the currently processing node."""
+        return self._current_node_id == node_id
+
+    def put_queue_unlocked(self, node_id: str) -> None:
+        """Add node to queue. Caller must hold lock (e.g. via with_lock)."""
+        self._queue.put_nowait(node_id)
+
+    def cancel_current_task(self) -> bool:
+        """Cancel the currently running task. Returns True if a task was cancelled."""
+        if self._current_task and not self._current_task.done():
+            self._current_task.cancel()
+            return True
+        return False
+
+    def set_node_error_sync(self, node: MessageNode, error_message: str) -> None:
+        """Synchronously mark a node as ERROR. Caller must ensure no concurrent access."""
+        node.state = MessageState.ERROR
+        node.error_message = error_message
+        node.completed_at = datetime.now(UTC)
+
+    def drain_queue_and_mark_cancelled(
+        self, error_message: str = "Cancelled by user"
+    ) -> list[MessageNode]:
+        """
+        Drain the queue, mark each node as ERROR, and return affected nodes.
+        Does not acquire lock; caller must ensure no concurrent queue access.
+        """
+        nodes: list[MessageNode] = []
+        while True:
+            try:
+                node_id = self._queue.get_nowait()
+            except asyncio.QueueEmpty:
+                break
+            node = self._nodes.get(node_id)
+            if node:
+                self.set_node_error_sync(node, error_message)
+                nodes.append(node)
+        return nodes
+
+    def reset_processing_state(self) -> None:
+        """Reset processing flags after cancel/cleanup."""
+        self._is_processing = False
+        self._current_node_id = None
+
+    @property
+    def current_node_id(self) -> str | None:
+        """Get the ID of the node currently being processed."""
+        return self._current_node_id
+
+    def to_dict(self) -> dict:
+        """Serialize tree to dictionary."""
+        return {
+            "root_id": self.root_id,
+            "nodes": {nid: node.to_dict() for nid, node in self._nodes.items()},
+        }
+
+    def _add_node_from_dict(self, node: MessageNode) -> None:
+        """Register a deserialized node into the tree's internal indices."""
+        self._nodes[node.node_id] = node
+        self._status_to_node[node.status_message_id] = node.node_id
+
+    @classmethod
+    def from_dict(cls, data: dict) -> MessageTree:
+        """Deserialize tree from dictionary."""
+        root_id = data["root_id"]
+        nodes_data = data["nodes"]
+
+        # Create root node first
+        root_node = MessageNode.from_dict(nodes_data[root_id])
+        tree = cls(root_node)
+
+        # Add remaining nodes and build status->node index
+        for node_id, node_data in nodes_data.items():
+            if node_id != root_id:
+                node = MessageNode.from_dict(node_data)
+                tree._add_node_from_dict(node)
+
+        return tree
+
+    def all_nodes(self) -> list[MessageNode]:
+        """Get all nodes in the tree."""
+        return list(self._nodes.values())
+
+    def has_node(self, node_id: str) -> bool:
+        """Check if a node exists in this tree."""
+        return node_id in self._nodes
+
+    def find_node_by_status_message(self, status_msg_id: str) -> MessageNode | None:
+        """Find the node that has this status message ID (O(1) lookup)."""
+        node_id = self._status_to_node.get(status_msg_id)
+        return self._nodes.get(node_id) if node_id else None
+
+    def get_descendants(self, node_id: str) -> list[str]:
+        """
+        Get node_id and all descendant IDs (subtree).
+
+        Returns:
+            List of node IDs including the given node.
+        """
+        if node_id not in self._nodes:
+            return []
+        result: list[str] = []
+        stack = [node_id]
+        while stack:
+            nid = stack.pop()
+            result.append(nid)
+            node = self._nodes.get(nid)
+            if node:
+                stack.extend(node.children_ids)
+        return result
+
+    def remove_branch(self, branch_root_id: str) -> list[MessageNode]:
+        """
+        Remove a subtree (branch_root and all descendants) from the tree.
+
+        Updates parent's children_ids. Caller must hold lock for consistency.
+        Does not acquire lock internally.
+
+        Returns:
+            List of removed nodes.
+        """
+        if branch_root_id not in self._nodes:
+            return []
+
+        parent = self.get_parent(branch_root_id)
+        removed = []
+        for nid in self.get_descendants(branch_root_id):
+            node = self._nodes.get(nid)
+            if node:
+                removed.append(node)
+                del self._nodes[nid]
+                del self._status_to_node[node.status_message_id]
+
+        if parent and branch_root_id in parent.children_ids:
+            parent.children_ids = [
+                c for c in parent.children_ids if c != branch_root_id
+            ]
+
+        logger.debug(f"Removed branch {branch_root_id} ({len(removed)} nodes)")
+        return removed

Claude_Code/messaging/trees/processor.py

@@ -0,0 +1,165 @@
+"""Async queue processor for message trees.
+
+Handles the async processing lifecycle of tree nodes.
+"""
+
+import asyncio
+from collections.abc import Awaitable, Callable
+
+from loguru import logger
+
+from providers.common import get_user_facing_error_message
+
+from .data import MessageNode, MessageState, MessageTree
+
+
+class TreeQueueProcessor:
+    """
+    Handles async queue processing for a single tree.
+
+    Separates the async processing logic from the data management.
+    """
+
+    def __init__(
+        self,
+        queue_update_callback: Callable[[MessageTree], Awaitable[None]] | None = None,
+        node_started_callback: Callable[[MessageTree, str], Awaitable[None]]
+        | None = None,
+    ):
+        self._queue_update_callback = queue_update_callback
+        self._node_started_callback = node_started_callback
+
+    def set_queue_update_callback(
+        self,
+        queue_update_callback: Callable[[MessageTree], Awaitable[None]] | None,
+    ) -> None:
+        """Update the callback used to refresh queue positions."""
+        self._queue_update_callback = queue_update_callback
+
+    def set_node_started_callback(
+        self,
+        node_started_callback: Callable[[MessageTree, str], Awaitable[None]] | None,
+    ) -> None:
+        """Update the callback used when a queued node starts processing."""
+        self._node_started_callback = node_started_callback
+
+    async def _notify_queue_updated(self, tree: MessageTree) -> None:
+        """Invoke queue update callback if set."""
+        if not self._queue_update_callback:
+            return
+        try:
+            await self._queue_update_callback(tree)
+        except Exception as e:
+            logger.warning(f"Queue update callback failed: {e}")
+
+    async def _notify_node_started(self, tree: MessageTree, node_id: str) -> None:
+        """Invoke node started callback if set."""
+        if not self._node_started_callback:
+            return
+        try:
+            await self._node_started_callback(tree, node_id)
+        except Exception as e:
+            logger.warning(f"Node started callback failed: {e}")
+
+    async def process_node(
+        self,
+        tree: MessageTree,
+        node: MessageNode,
+        processor: Callable[[str, MessageNode], Awaitable[None]],
+    ) -> None:
+        """Process a single node and then check the queue."""
+        # Skip if already in terminal state (e.g. from error propagation)
+        if node.state == MessageState.ERROR:
+            logger.info(
+                f"Skipping node {node.node_id} as it is already in state {node.state}"
+            )
+            # Still need to check for next messages
+            await self._process_next(tree, processor)
+            return
+
+        try:
+            await processor(node.node_id, node)
+        except asyncio.CancelledError:
+            logger.info(f"Task for node {node.node_id} was cancelled")
+            raise
+        except Exception as e:
+            logger.error(f"Error processing node {node.node_id}: {e}")
+            await tree.update_state(
+                node.node_id,
+                MessageState.ERROR,
+                error_message=get_user_facing_error_message(e),
+            )
+        finally:
+            async with tree.with_lock():
+                tree.clear_current_node()
+            # Check if there are more messages in the queue
+            await self._process_next(tree, processor)
+
+    async def _process_next(
+        self,
+        tree: MessageTree,
+        processor: Callable[[str, MessageNode], Awaitable[None]],
+    ) -> None:
+        """Process the next message in queue, if any."""
+        next_node_id = None
+        node = None
+        async with tree.with_lock():
+            next_node_id = await tree.dequeue()
+
+            if not next_node_id:
+                tree.set_processing_state(None, False)
+                logger.debug(f"Tree {tree.root_id} queue empty, marking as free")
+                return
+
+            tree.set_processing_state(next_node_id, True)
+            logger.info(f"Processing next queued node {next_node_id}")
+
+            # Process next node (outside lock)
+            node = tree.get_node(next_node_id)
+            if node:
+                tree.set_current_task(
+                    asyncio.create_task(self.process_node(tree, node, processor))
+                )
+
+        # Notify that this node has started processing and refresh queue positions.
+        if next_node_id:
+            await self._notify_node_started(tree, next_node_id)
+            await self._notify_queue_updated(tree)
+
+    async def enqueue_and_start(
+        self,
+        tree: MessageTree,
+        node_id: str,
+        processor: Callable[[str, MessageNode], Awaitable[None]],
+    ) -> bool:
+        """
+        Enqueue a node or start processing immediately.
+
+        Args:
+            tree: The message tree
+            node_id: Node to process
+            processor: Async function to process the node
+
+        Returns:
+            True if queued, False if processing immediately
+        """
+        async with tree.with_lock():
+            if tree.is_processing:
+                tree.put_queue_unlocked(node_id)
+                queue_size = tree.get_queue_size()
+                logger.info(f"Queued node {node_id}, position {queue_size}")
+                return True
+            else:
+                tree.set_processing_state(node_id, True)
+
+                # Process outside the lock
+                node = tree.get_node(node_id)
+                if node:
+                    tree.set_current_task(
+                        asyncio.create_task(self.process_node(tree, node, processor))
+                    )
+                return False
+
+    def cancel_current(self, tree: MessageTree) -> bool:
+        """Cancel the currently running task in a tree."""
+        return tree.cancel_current_task()