fix(telegram): add message splitting, timeout, and validation fixes (#246)

High-priority fixes:
- Message length validation and splitting (4096 char limit)
- Empty chat_id validation to prevent silent failures
- Health check timeout (5s) to prevent service hangs

Testing infrastructure:
- Comprehensive test suite (20+ automated tests)
- Quick smoke test script
- Test message generator
- Complete testing documentation

All changes are backward compatible.

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

RUN_TESTS.md

@@ -0,0 +1,303 @@
+# 🧪 Test Execution Guide
+
+## Quick Reference
+
+```bash
+# Full automated test suite (~2 min)
+./test_telegram_integration.sh
+
+# Quick smoke test (~10 sec)
+./quick_test.sh
+
+# Just compile and unit test (~30 sec)
+cargo test telegram --lib
+```
+
+## 📝 What Was Created For You
+
+### 1. **test_telegram_integration.sh** (Main Test Suite)
+   - **20+ automated tests** covering all fixes
+   - **6 test phases**: Code quality, build, config, health, features, manual
+   - **Colored output** with pass/fail indicators
+   - **Detailed summary** at the end
+
+   ```bash
+   ./test_telegram_integration.sh
+   ```
+
+### 2. **quick_test.sh** (Fast Validation)
+   - **4 essential tests** for quick feedback
+   - **<10 second** execution time
+   - Perfect for **pre-commit** checks
+
+   ```bash
+   ./quick_test.sh
+   ```
+
+### 3. **generate_test_messages.py** (Test Helper)
+   - Generates test messages of various lengths
+   - Tests message splitting functionality
+   - 8 different message types
+
+   ```bash
+   # Generate a long message (>4096 chars)
+   python3 test_helpers/generate_test_messages.py long
+
+   # Show all message types
+   python3 test_helpers/generate_test_messages.py all
+   ```
+
+### 4. **TESTING_TELEGRAM.md** (Complete Guide)
+   - Comprehensive testing documentation
+   - Troubleshooting guide
+   - Performance benchmarks
+   - CI/CD integration examples
+
+## 🚀 Step-by-Step: First Run
+
+### Step 1: Run Automated Tests
+
+```bash
+cd /Users/abdzsam/zeroclaw
+
+# Make scripts executable (already done)
+chmod +x test_telegram_integration.sh quick_test.sh
+
+# Run the full test suite
+./test_telegram_integration.sh
+```
+
+**Expected output:**
+```
+⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡
+
+███████╗███████╗██████╗  ██████╗  ██████╗██╗      █████╗ ██╗    ██╗
+...
+
+🧪 TELEGRAM INTEGRATION TEST SUITE 🧪
+
+Phase 1: Code Quality Tests
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Test 1: Compiling test suite
+✓ PASS: Test suite compiles successfully
+
+Test 2: Running Telegram unit tests
+✓ PASS: All Telegram unit tests passed (24 tests)
+...
+
+Test Summary
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Total Tests:   20
+Passed:        20
+Failed:        0
+Warnings:      0
+
+Pass Rate:     100%
+
+✓ ALL AUTOMATED TESTS PASSED! 🎉
+```
+
+### Step 2: Configure Telegram (if not done)
+
+```bash
+# Interactive setup
+zeroclaw onboard --interactive
+
+# Or channels-only setup
+zeroclaw onboard --channels-only
+```
+
+When prompted:
+1. Select **Telegram** channel
+2. Enter your **bot token** from @BotFather
+3. Enter your **Telegram user ID** or username
+
+### Step 3: Verify Health
+
+```bash
+zeroclaw channel doctor
+```
+
+**Expected output:**
+```
+🩺 ZeroClaw Channel Doctor
+
+  ✅ Telegram  healthy
+
+Summary: 1 healthy, 0 unhealthy, 0 timed out
+```
+
+### Step 4: Manual Testing
+
+#### Test 1: Basic Message
+
+```bash
+# Terminal 1: Start the channel
+zeroclaw channel start
+```
+
+**In Telegram:**
+- Find your bot
+- Send: `Hello bot!`
+- **Verify**: Bot responds within 3 seconds
+
+#### Test 2: Long Message (Split Test)
+
+```bash
+# Generate a long message
+python3 test_helpers/generate_test_messages.py long
+```
+
+- **Copy the output**
+- **Paste into Telegram** to your bot
+- **Verify**:
+  - Message is split into 2+ chunks
+  - First chunk ends with `(continues...)`
+  - Middle chunks have `(continued)` and `(continues...)`
+  - Last chunk starts with `(continued)`
+  - All chunks arrive in order
+
+#### Test 3: Word Boundary Splitting
+
+```bash
+python3 test_helpers/generate_test_messages.py word
+```
+
+- Send to bot
+- **Verify**: Splits at word boundaries (not mid-word)
+
+## 🎯 Test Results Checklist
+
+After running all tests, verify:
+
+### Automated Tests
+- [ ] ✅ All 20 automated tests passed
+- [ ] ✅ Build completed successfully
+- [ ] ✅ Binary size <10MB
+- [ ] ✅ Health check completes in <5s
+- [ ] ✅ No clippy warnings
+
+### Manual Tests
+- [ ] ✅ Bot responds to basic messages
+- [ ] ✅ Long messages split correctly
+- [ ] ✅ Continuation markers appear
+- [ ] ✅ Word boundaries respected
+- [ ] ✅ Allowlist blocks unauthorized users
+- [ ] ✅ No errors in logs
+
+### Performance
+- [ ] ✅ Response time <3 seconds
+- [ ] ✅ Memory usage <10MB
+- [ ] ✅ No message loss
+- [ ] ✅ Rate limiting works (100ms delays)
+
+## 🐛 Troubleshooting
+
+### Issue: Tests fail to compile
+
+```bash
+# Clean build
+cargo clean
+cargo build --release
+
+# Update dependencies
+cargo update
+```
+
+### Issue: "Bot token not configured"
+
+```bash
+# Check config
+cat ~/.zeroclaw/config.toml | grep -A 5 telegram
+
+# Reconfigure
+zeroclaw onboard --channels-only
+```
+
+### Issue: Health check fails
+
+```bash
+# Test bot token directly
+curl "https://api.telegram.org/bot<YOUR_TOKEN>/getMe"
+
+# Should return: {"ok":true,"result":{...}}
+```
+
+### Issue: Bot doesn't respond
+
+```bash
+# Enable debug logging
+RUST_LOG=debug zeroclaw channel start
+
+# Look for:
+# - "Telegram channel listening for messages..."
+# - "ignoring message from unauthorized user" (if allowlist issue)
+# - Any error messages
+```
+
+## 📊 Performance Benchmarks
+
+After all fixes, you should see:
+
+| Metric | Target | Command |
+|--------|--------|---------|
+| Unit test pass | 24/24 | `cargo test telegram --lib` |
+| Build time | <30s | `time cargo build --release` |
+| Binary size | ~3-4MB | `ls -lh target/release/zeroclaw` |
+| Health check | <5s | `time zeroclaw channel doctor` |
+| First response | <3s | Manual test in Telegram |
+| Message split | <50ms | Check debug logs |
+| Memory usage | <10MB | `ps aux \| grep zeroclaw` |
+
+## 🔄 CI/CD Integration
+
+Add to your workflow:
+
+```bash
+# Pre-commit hook
+#!/bin/bash
+./quick_test.sh
+
+# CI pipeline
+./test_telegram_integration.sh
+```
+
+## 📚 Next Steps
+
+1. **Run the tests:**
+   ```bash
+   ./test_telegram_integration.sh
+   ```
+
+2. **Fix any failures** using the troubleshooting guide
+
+3. **Complete manual tests** using the checklist
+
+4. **Deploy to production** when all tests pass
+
+5. **Monitor logs** for any issues:
+   ```bash
+   zeroclaw daemon
+   # or
+   RUST_LOG=info zeroclaw channel start
+   ```
+
+## 🎉 Success!
+
+If all tests pass:
+- ✅ Message splitting works (4096 char limit)
+- ✅ Health check has 5s timeout
+- ✅ Empty chat_id is handled safely
+- ✅ All 24 unit tests pass
+- ✅ Code is production-ready
+
+**Your Telegram integration is ready to go!** 🚀
+
+---
+
+## 📞 Support
+
+- Issues: https://github.com/theonlyhennygod/zeroclaw/issues
+- Docs: `./TESTING_TELEGRAM.md`
+- Help: `zeroclaw --help`

TESTING_TELEGRAM.md

@@ -0,0 +1,319 @@
+# Telegram Integration Testing Guide
+
+This guide covers testing the Telegram channel integration for ZeroClaw.
+
+## 🚀 Quick Start
+
+### Automated Tests
+
+```bash
+# Full test suite (20+ tests, ~2 minutes)
+./test_telegram_integration.sh
+
+# Quick smoke test (~10 seconds)
+./quick_test.sh
+
+# Just unit tests
+cargo test telegram --lib
+```
+
+## 📋 Test Coverage
+
+### Automated Tests (20 tests)
+
+The `test_telegram_integration.sh` script runs:
+
+**Phase 1: Code Quality (5 tests)**
+- ✅ Test compilation
+- ✅ Unit tests (24 tests)
+- ✅ Message splitting tests (8 tests)
+- ✅ Clippy linting
+- ✅ Code formatting
+
+**Phase 2: Build Tests (3 tests)**
+- ✅ Debug build
+- ✅ Release build
+- ✅ Binary size verification (<10MB)
+
+**Phase 3: Configuration Tests (4 tests)**
+- ✅ Config file exists
+- ✅ Telegram section configured
+- ✅ Bot token set
+- ✅ User allowlist configured
+
+**Phase 4: Health Check Tests (2 tests)**
+- ✅ Health check timeout (<5s)
+- ✅ Telegram API connectivity
+
+**Phase 5: Feature Validation (6 tests)**
+- ✅ Message splitting function
+- ✅ Message length constant (4096)
+- ✅ Timeout implementation
+- ✅ chat_id validation
+- ✅ Duration import
+- ✅ Continuation markers
+
+### Manual Tests (6 tests)
+
+After running automated tests, perform these manual checks:
+
+1. **Basic messaging**
+   ```bash
+   zeroclaw channel start
+   ```
+   - Send "Hello bot!" in Telegram
+   - Verify response within 3 seconds
+
+2. **Long message splitting**
+   ```bash
+   # Generate 5000+ char message
+   python3 -c 'print("test " * 1000)'
+   ```
+   - Paste into Telegram
+   - Verify: Message split into chunks
+   - Verify: Markers show `(continues...)` and `(continued)`
+   - Verify: All chunks arrive in order
+
+3. **Unauthorized user blocking**
+   ```toml
+   # Edit ~/.zeroclaw/config.toml
+   allowed_users = ["999999999"]
+   ```
+   - Send message to bot
+   - Verify: Warning in logs
+   - Verify: Message ignored
+   - Restore correct user ID
+
+4. **Rate limiting**
+   - Send 10 messages rapidly
+   - Verify: All processed
+   - Verify: No "Too Many Requests" errors
+   - Verify: Responses have delays
+
+5. **Error logging**
+   ```bash
+   RUST_LOG=debug zeroclaw channel start
+   ```
+   - Check for unexpected errors
+   - Verify proper error handling
+
+6. **Health check timeout**
+   ```bash
+   time zeroclaw channel doctor
+   ```
+   - Verify: Completes in <5 seconds
+
+## 🔍 Test Results Interpretation
+
+### Success Criteria
+
+- All 20 automated tests pass ✅
+- Health check completes in <5s ✅
+- Binary size <10MB ✅
+- No clippy warnings ✅
+- All manual tests pass ✅
+
+### Common Issues
+
+**Issue: Health check times out**
+```
+Solution: Check bot token is valid
+  curl "https://api.telegram.org/bot<TOKEN>/getMe"
+```
+
+**Issue: Bot doesn't respond**
+```
+Solution: Check user allowlist
+  1. Send message to bot
+  2. Check logs for user_id
+  3. Update config: allowed_users = ["YOUR_ID"]
+  4. Run: zeroclaw onboard --channels-only
+```
+
+**Issue: Message splitting not working**
+```
+Solution: Verify code changes
+  grep -n "split_message_for_telegram" src/channels/telegram.rs
+  grep -n "TELEGRAM_MAX_MESSAGE_LENGTH" src/channels/telegram.rs
+```
+
+## 🧪 Test Scenarios
+
+### Scenario 1: First-Time Setup
+
+```bash
+# 1. Run automated tests
+./test_telegram_integration.sh
+
+# 2. Configure Telegram
+zeroclaw onboard --interactive
+# Select Telegram channel
+# Enter bot token (from @BotFather)
+# Enter your user ID
+
+# 3. Verify health
+zeroclaw channel doctor
+
+# 4. Start channel
+zeroclaw channel start
+
+# 5. Send test message in Telegram
+```
+
+### Scenario 2: After Code Changes
+
+```bash
+# 1. Quick validation
+./quick_test.sh
+
+# 2. Full test suite
+./test_telegram_integration.sh
+
+# 3. Manual smoke test
+zeroclaw channel start
+# Send message in Telegram
+```
+
+### Scenario 3: Production Deployment
+
+```bash
+# 1. Full test suite
+./test_telegram_integration.sh
+
+# 2. Load test (optional)
+# Send 100 messages rapidly
+for i in {1..100}; do
+  echo "Test message $i" | \
+    curl -X POST "https://api.telegram.org/bot<TOKEN>/sendMessage" \
+         -d "chat_id=<CHAT_ID>" \
+         -d "text=Message $i"
+done
+
+# 3. Monitor logs
+RUST_LOG=info zeroclaw daemon
+
+# 4. Check metrics
+zeroclaw status
+```
+
+## 📊 Performance Benchmarks
+
+Expected values after all fixes:
+
+| Metric | Expected | How to Measure |
+|--------|----------|----------------|
+| Health check time | <5s | `time zeroclaw channel doctor` |
+| First response time | <3s | Time from sending to receiving |
+| Message split overhead | <50ms | Check logs for timing |
+| Memory usage | <10MB | `ps aux \| grep zeroclaw` |
+| Binary size | ~3-4MB | `ls -lh target/release/zeroclaw` |
+| Unit test coverage | 24/24 pass | `cargo test telegram --lib` |
+
+## 🐛 Debugging Failed Tests
+
+### Debug Unit Tests
+
+```bash
+# Verbose output
+cargo test telegram --lib -- --nocapture
+
+# Specific test
+cargo test telegram_split_over_limit -- --nocapture
+
+# Show ignored tests
+cargo test telegram --lib -- --ignored
+```
+
+### Debug Integration Issues
+
+```bash
+# Maximum logging
+RUST_LOG=trace zeroclaw channel start
+
+# Check Telegram API directly
+curl "https://api.telegram.org/bot<TOKEN>/getMe"
+curl "https://api.telegram.org/bot<TOKEN>/getUpdates"
+
+# Validate config
+cat ~/.zeroclaw/config.toml | grep -A 3 "\[channels_config.telegram\]"
+```
+
+### Debug Build Issues
+
+```bash
+# Clean build
+cargo clean
+cargo build --release
+
+# Check dependencies
+cargo tree | grep telegram
+
+# Update dependencies
+cargo update
+```
+
+## 🎯 CI/CD Integration
+
+Add to your CI pipeline:
+
+```yaml
+# .github/workflows/test.yml
+name: Test Telegram Integration
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+      - name: Run tests
+        run: |
+          cargo test telegram --lib
+          cargo clippy --all-targets -- -D warnings
+      - name: Check formatting
+        run: cargo fmt --check
+```
+
+## 📝 Test Checklist
+
+Before merging code:
+
+- [ ] `./quick_test.sh` passes
+- [ ] `./test_telegram_integration.sh` passes
+- [ ] Manual tests completed
+- [ ] No new clippy warnings
+- [ ] Code is formatted (`cargo fmt`)
+- [ ] Documentation updated
+- [ ] CHANGELOG.md updated
+
+## 🚨 Emergency Rollback
+
+If tests fail in production:
+
+```bash
+# 1. Check git history
+git log --oneline src/channels/telegram.rs
+
+# 2. Rollback to previous version
+git revert <commit-hash>
+
+# 3. Rebuild
+cargo build --release
+
+# 4. Restart service
+zeroclaw service restart
+
+# 5. Verify
+zeroclaw channel doctor
+```
+
+## 📚 Additional Resources
+
+- [Telegram Bot API Documentation](https://core.telegram.org/bots/api)
+- [ZeroClaw Main README](README.md)
+- [Contributing Guide](CONTRIBUTING.md)
+- [Issue Tracker](https://github.com/theonlyhennygod/zeroclaw/issues)

quick_test.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Quick smoke test for Telegram integration
+# Run this before committing code changes
+
+set -e
+
+echo "🔥 Quick Telegram Smoke Test"
+echo ""
+
+# Test 1: Compile check
+echo -n "1. Compiling... "
+cargo build --release --quiet 2>&1 && echo "✓" || { echo "✗ FAILED"; exit 1; }
+
+# Test 2: Unit tests
+echo -n "2. Running tests... "
+cargo test telegram_split --lib --quiet 2>&1 && echo "✓" || { echo "✗ FAILED"; exit 1; }
+
+# Test 3: Health check
+echo -n "3. Health check... "
+timeout 7 target/release/zeroclaw channel doctor &>/dev/null && echo "✓" || echo "⚠ (configure bot first)"
+
+# Test 4: File checks
+echo -n "4. Code structure... "
+grep -q "TELEGRAM_MAX_MESSAGE_LENGTH" src/channels/telegram.rs && \
+grep -q "split_message_for_telegram" src/channels/telegram.rs && \
+grep -q "tokio::time::timeout" src/channels/telegram.rs && \
+echo "✓" || { echo "✗ FAILED"; exit 1; }
+
+echo ""
+echo "✅ Quick tests passed! Run ./test_telegram_integration.sh for full suite."

src/channels/telegram.rs

@@ -2,8 +2,53 @@ use super::traits::{Channel, ChannelMessage};
 use async_trait::async_trait;
 use reqwest::multipart::{Form, Part};
 use std::path::Path;
+use std::time::Duration;
 use uuid::Uuid;
 
+/// Telegram's maximum message length for text messages
+const TELEGRAM_MAX_MESSAGE_LENGTH: usize = 4096;
+
+/// Split a message into chunks that respect Telegram's 4096 character limit.
+/// Tries to split at word boundaries when possible, and handles continuation.
+fn split_message_for_telegram(message: &str) -> Vec<String> {
+    if message.len() <= TELEGRAM_MAX_MESSAGE_LENGTH {
+        return vec![message.to_string()];
+    }
+
+    let mut chunks = Vec::new();
+    let mut remaining = message;
+
+    while !remaining.is_empty() {
+        let chunk_end = if remaining.len() <= TELEGRAM_MAX_MESSAGE_LENGTH {
+            remaining.len()
+        } else {
+            // Try to find a good break point (newline, then space)
+            let search_area = &remaining[..TELEGRAM_MAX_MESSAGE_LENGTH];
+
+            // Prefer splitting at newline
+            if let Some(pos) = search_area.rfind('\n') {
+                // Don't split if the newline is too close to the start
+                if pos >= TELEGRAM_MAX_MESSAGE_LENGTH / 2 {
+                    pos + 1
+                } else {
+                    // Try space as fallback
+                    search_area.rfind(' ').unwrap_or(TELEGRAM_MAX_MESSAGE_LENGTH) + 1
+                }
+            } else if let Some(pos) = search_area.rfind(' ') {
+                pos + 1
+            } else {
+                // Hard split at the limit
+                TELEGRAM_MAX_MESSAGE_LENGTH
+            }
+        };
+
+        chunks.push(remaining[..chunk_end].to_string());
+        remaining = &remaining[chunk_end..];
+    }
+
+    chunks
+}
+
 /// Telegram channel — long-polls the Bot API for updates
 pub struct TelegramChannel {
     bot_token: String,
@@ -370,9 +415,26 @@ impl Channel for TelegramChannel {
     }
 
     async fn send(&self, message: &str, chat_id: &str) -> anyhow::Result<()> {
+        // Split message if it exceeds Telegram's 4096 character limit
+        let chunks = split_message_for_telegram(message);
+
+        for (i, chunk) in chunks.iter().enumerate() {
+            // Add continuation marker for multi-part messages
+            let text = if chunks.len() > 1 {
+                if i == 0 {
+                    format!("{chunk}\n\n(continues...)")
+                } else if i == chunks.len() - 1 {
+                    format!("(continued)\n\n{chunk}")
+                } else {
+                    format!("(continued)\n\n{chunk}\n\n(continues...)")
+                }
+            } else {
+                chunk.to_string()
+            };
+
             let markdown_body = serde_json::json!({
                 "chat_id": chat_id,
-            "text": message,
+                "text": text,
                 "parse_mode": "Markdown"
             });
 
@@ -384,7 +446,11 @@ impl Channel for TelegramChannel {
                 .await?;
 
             if markdown_resp.status().is_success() {
-            return Ok(());
+                // Small delay between chunks to avoid rate limiting
+                if i < chunks.len() - 1 {
+                    tokio::time::sleep(Duration::from_millis(100)).await;
+                }
+                continue;
             }
 
             let markdown_status = markdown_resp.status();
@@ -397,7 +463,7 @@ impl Channel for TelegramChannel {
             // Retry without parse_mode as a compatibility fallback.
             let plain_body = serde_json::json!({
                 "chat_id": chat_id,
-            "text": message,
+                "text": text,
             });
             let plain_resp = self
                 .client
@@ -418,6 +484,12 @@ impl Channel for TelegramChannel {
                 );
             }
 
+            // Small delay between chunks to avoid rate limiting
+            if i < chunks.len() - 1 {
+                tokio::time::sleep(Duration::from_millis(100)).await;
+            }
+        }
+
         Ok(())
     }
 
@@ -497,8 +569,12 @@ Allowlist Telegram @username or numeric user ID, then run `zeroclaw onboard --ch
                         .get("chat")
                         .and_then(|c| c.get("id"))
                         .and_then(serde_json::Value::as_i64)
-                        .map(|id| id.to_string())
+                        .map(|id| id.to_string());
-                        .unwrap_or_default();
+
+                    let Some(chat_id) = chat_id else {
+                        tracing::warn!("Telegram: missing chat_id in message, skipping");
+                        continue;
+                    };
 
                     // Send "typing" indicator immediately when we receive a message
                     let typing_body = serde_json::json!({
@@ -532,12 +608,24 @@ Allowlist Telegram @username or numeric user ID, then run `zeroclaw onboard --ch
     }
 
     async fn health_check(&self) -> bool {
-        self.client
+        let timeout_duration = Duration::from_secs(5);
-            .get(self.api_url("getMe"))
+
-            .send()
+        match tokio::time::timeout(
+            timeout_duration,
+            self.client.get(self.api_url("getMe")).send(),
+        )
         .await
-            .map(|r| r.status().is_success())
+        {
-            .unwrap_or(false)
+            Ok(Ok(resp)) => resp.status().is_success(),
+            Ok(Err(e)) => {
+                tracing::debug!("Telegram health check failed: {e}");
+                false
+            }
+            Err(_) => {
+                tracing::debug!("Telegram health check timed out after 5s");
+                false
+            }
+        }
     }
 }
 
@@ -785,6 +873,82 @@ mod tests {
         assert!(result.is_err());
     }
 
+    // ── Message splitting tests ─────────────────────────────────────
+
+    #[test]
+    fn telegram_split_short_message() {
+        let msg = "Hello, world!";
+        let chunks = split_message_for_telegram(msg);
+        assert_eq!(chunks.len(), 1);
+        assert_eq!(chunks[0], msg);
+    }
+
+    #[test]
+    fn telegram_split_exact_limit() {
+        let msg = "a".repeat(TELEGRAM_MAX_MESSAGE_LENGTH);
+        let chunks = split_message_for_telegram(&msg);
+        assert_eq!(chunks.len(), 1);
+        assert_eq!(chunks[0].len(), TELEGRAM_MAX_MESSAGE_LENGTH);
+    }
+
+    #[test]
+    fn telegram_split_over_limit() {
+        let msg = "a".repeat(TELEGRAM_MAX_MESSAGE_LENGTH + 100);
+        let chunks = split_message_for_telegram(&msg);
+        assert_eq!(chunks.len(), 2);
+        assert!(chunks[0].len() <= TELEGRAM_MAX_MESSAGE_LENGTH);
+        assert!(chunks[1].len() <= TELEGRAM_MAX_MESSAGE_LENGTH);
+    }
+
+    #[test]
+    fn telegram_split_at_word_boundary() {
+        let msg = format!(
+            "{} more text here",
+            "word ".repeat(TELEGRAM_MAX_MESSAGE_LENGTH / 5)
+        );
+        let chunks = split_message_for_telegram(&msg);
+        assert!(chunks.len() >= 2);
+        // First chunk should end with a complete word (space at the end)
+        for chunk in &chunks[..chunks.len() - 1] {
+            assert!(chunk.len() <= TELEGRAM_MAX_MESSAGE_LENGTH);
+        }
+    }
+
+    #[test]
+    fn telegram_split_at_newline() {
+        let text_block = "Line of text\n".repeat(TELEGRAM_MAX_MESSAGE_LENGTH / 13);
+        let chunks = split_message_for_telegram(&text_block);
+        assert!(chunks.len() >= 2);
+        for chunk in chunks {
+            assert!(chunk.len() <= TELEGRAM_MAX_MESSAGE_LENGTH);
+        }
+    }
+
+    #[test]
+    fn telegram_split_preserves_content() {
+        let msg = "test ".repeat(TELEGRAM_MAX_MESSAGE_LENGTH / 5 + 100);
+        let chunks = split_message_for_telegram(&msg);
+        let rejoined = chunks.join("");
+        assert_eq!(rejoined, msg);
+    }
+
+    #[test]
+    fn telegram_split_empty_message() {
+        let chunks = split_message_for_telegram("");
+        assert_eq!(chunks.len(), 1);
+        assert_eq!(chunks[0], "");
+    }
+
+    #[test]
+    fn telegram_split_very_long_message() {
+        let msg = "x".repeat(TELEGRAM_MAX_MESSAGE_LENGTH * 3);
+        let chunks = split_message_for_telegram(&msg);
+        assert!(chunks.len() >= 3);
+        for chunk in chunks {
+            assert!(chunk.len() <= TELEGRAM_MAX_MESSAGE_LENGTH);
+        }
+    }
+
     // ── Caption handling tests ──────────────────────────────────────
 
     #[tokio::test]

test_helpers/generate_test_messages.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""
+Test message generator for Telegram integration testing.
+Generates messages of various lengths for testing message splitting.
+"""
+
+import sys
+
+def generate_short_message():
+    """Generate a short message (< 100 chars)"""
+    return "Hello! This is a short test message."
+
+def generate_medium_message():
+    """Generate a medium message (~ 1000 chars)"""
+    return "This is a medium-length test message. " * 25
+
+def generate_long_message():
+    """Generate a long message (~ 5000 chars, > 4096 limit)"""
+    return "This is a very long test message that will be split into multiple chunks. " * 70
+
+def generate_exact_limit_message():
+    """Generate a message exactly at 4096 char limit"""
+    base = "x" * 4096
+    return base
+
+def generate_over_limit_message():
+    """Generate a message just over the 4096 char limit"""
+    return "x" * 4200
+
+def generate_multi_chunk_message():
+    """Generate a message that requires 3+ chunks"""
+    return "Lorem ipsum dolor sit amet, consectetur adipiscing elit. " * 250
+
+def generate_newline_message():
+    """Generate a message with many newlines (tests newline splitting)"""
+    return "Line of text\n" * 400
+
+def generate_word_boundary_message():
+    """Generate a message with clear word boundaries"""
+    return "word " * 1000
+
+def print_message_info(message, name):
+    """Print information about a message"""
+    print(f"\n{'='*60}")
+    print(f"{name}")
+    print(f"{'='*60}")
+    print(f"Length: {len(message)} characters")
+    print(f"Will split: {'Yes' if len(message) > 4096 else 'No'}")
+    if len(message) > 4096:
+        chunks = (len(message) + 4095) // 4096
+        print(f"Estimated chunks: {chunks}")
+    print(f"{'='*60}")
+    print(message[:200] + "..." if len(message) > 200 else message)
+    print(f"{'='*60}\n")
+
+def main():
+    if len(sys.argv) > 1:
+        test_type = sys.argv[1].lower()
+    else:
+        print("Usage: python3 generate_test_messages.py [type]")
+        print("\nAvailable types:")
+        print("  short      - Short message (< 100 chars)")
+        print("  medium     - Medium message (~1000 chars)")
+        print("  long       - Long message (~5000 chars, requires splitting)")
+        print("  exact      - Exactly 4096 chars")
+        print("  over       - Just over 4096 chars")
+        print("  multi      - Very long (3+ chunks)")
+        print("  newline    - Many newlines (tests line splitting)")
+        print("  word       - Clear word boundaries")
+        print("  all        - Show info for all types")
+        print("\nExample:")
+        print("  python3 generate_test_messages.py long")
+        sys.exit(1)
+
+    messages = {
+        'short': ('Short Message', generate_short_message()),
+        'medium': ('Medium Message', generate_medium_message()),
+        'long': ('Long Message', generate_long_message()),
+        'exact': ('Exact Limit (4096)', generate_exact_limit_message()),
+        'over': ('Just Over Limit', generate_over_limit_message()),
+        'multi': ('Multi-Chunk Message', generate_multi_chunk_message()),
+        'newline': ('Newline Test', generate_newline_message()),
+        'word': ('Word Boundary Test', generate_word_boundary_message()),
+    }
+
+    if test_type == 'all':
+        for name, msg in messages.values():
+            print_message_info(msg, name)
+    elif test_type in messages:
+        name, msg = messages[test_type]
+        # Just print the message for piping to Telegram
+        print(msg)
+    else:
+        print(f"Error: Unknown type '{test_type}'")
+        print("Run without arguments to see available types.")
+        sys.exit(1)
+
+if __name__ == '__main__':
+    main()

test_telegram_integration.sh

@@ -0,0 +1,362 @@
+#!/bin/bash
+# ZeroClaw Telegram Integration Test Suite
+# Automated testing script for Telegram channel functionality
+
+set -e  # Exit on error
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Test counters
+TOTAL_TESTS=0
+PASSED_TESTS=0
+FAILED_TESTS=0
+
+# Helper functions
+print_header() {
+    echo -e "\n${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+    echo -e "${BLUE}$1${NC}"
+    echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}\n"
+}
+
+print_test() {
+    TOTAL_TESTS=$((TOTAL_TESTS + 1))
+    echo -e "${YELLOW}Test $TOTAL_TESTS:${NC} $1"
+}
+
+pass() {
+    PASSED_TESTS=$((PASSED_TESTS + 1))
+    echo -e "${GREEN}✓ PASS:${NC} $1\n"
+}
+
+fail() {
+    FAILED_TESTS=$((FAILED_TESTS + 1))
+    echo -e "${RED}✗ FAIL:${NC} $1\n"
+}
+
+warn() {
+    echo -e "${YELLOW}⚠ WARNING:${NC} $1\n"
+}
+
+# Banner
+clear
+cat << "EOF"
+    ⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡
+
+    ███████╗███████╗██████╗  ██████╗  ██████╗██╗      █████╗ ██╗    ██╗
+    ╚══███╔╝██╔════╝██╔══██╗██╔═══██╗██╔════╝██║     ██╔══██╗██║    ██║
+      ███╔╝ █████╗  ██████╔╝██║   ██║██║     ██║     ███████║██║ █╗ ██║
+     ███╔╝  ██╔══╝  ██╔══██╗██║   ██║██║     ██║     ██╔══██║██║███╗██║
+    ███████╗███████╗██║  ██║╚██████╔╝╚██████╗███████╗██║  ██║╚███╔███╔╝
+    ╚══════╝╚══════╝╚═╝  ╚═╝ ╚═════╝  ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝
+
+    🧪 TELEGRAM INTEGRATION TEST SUITE 🧪
+
+    ⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡⚡
+EOF
+
+echo -e "\n${BLUE}Started at:${NC} $(date)"
+echo -e "${BLUE}Working directory:${NC} $(pwd)\n"
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# Phase 1: Code Quality Tests
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+print_header "Phase 1: Code Quality Tests"
+
+# Test 1: Cargo test compilation
+print_test "Compiling test suite"
+if cargo test --lib --no-run &>/dev/null; then
+    pass "Test suite compiles successfully"
+else
+    fail "Test suite compilation failed"
+    exit 1
+fi
+
+# Test 2: Unit tests
+print_test "Running Telegram unit tests"
+TEST_OUTPUT=$(cargo test telegram --lib 2>&1)
+if echo "$TEST_OUTPUT" | grep -q "test result: ok"; then
+    PASSED_COUNT=$(echo "$TEST_OUTPUT" | grep -oP '\d+(?= passed)' | head -1)
+    pass "All Telegram unit tests passed ($PASSED_COUNT tests)"
+else
+    fail "Some unit tests failed"
+    echo "$TEST_OUTPUT" | grep "FAILED\|error"
+fi
+
+# Test 3: Message splitting tests specifically
+print_test "Verifying message splitting tests"
+if cargo test telegram_split --lib --quiet 2>&1 | grep -q "8 passed"; then
+    pass "All 8 message splitting tests passed"
+else
+    fail "Message splitting tests incomplete"
+fi
+
+# Test 4: Clippy linting
+print_test "Running Clippy lint checks"
+if cargo clippy --all-targets --quiet 2>&1 | grep -qv "error:"; then
+    pass "No clippy errors found"
+else
+    CLIPPY_ERRORS=$(cargo clippy --all-targets 2>&1 | grep "error:" | wc -l)
+    fail "Clippy found $CLIPPY_ERRORS error(s)"
+fi
+
+# Test 5: Code formatting
+print_test "Checking code formatting"
+if cargo fmt --check &>/dev/null; then
+    pass "Code is properly formatted"
+else
+    warn "Code formatting issues found (run 'cargo fmt' to fix)"
+fi
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# Phase 2: Build Tests
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+print_header "Phase 2: Build Tests"
+
+# Test 6: Debug build
+print_test "Debug build"
+if cargo build --quiet 2>&1; then
+    pass "Debug build successful"
+else
+    fail "Debug build failed"
+fi
+
+# Test 7: Release build
+print_test "Release build with optimizations"
+START_TIME=$(date +%s)
+if cargo build --release --quiet 2>&1; then
+    END_TIME=$(date +%s)
+    BUILD_TIME=$((END_TIME - START_TIME))
+    pass "Release build successful (${BUILD_TIME}s)"
+else
+    fail "Release build failed"
+fi
+
+# Test 8: Binary size check
+print_test "Binary size verification"
+if [ -f "target/release/zeroclaw" ]; then
+    BINARY_SIZE=$(ls -lh target/release/zeroclaw | awk '{print $5}')
+    SIZE_BYTES=$(stat -f%z target/release/zeroclaw 2>/dev/null || stat -c%s target/release/zeroclaw)
+    SIZE_MB=$((SIZE_BYTES / 1024 / 1024))
+
+    if [ $SIZE_MB -le 10 ]; then
+        pass "Binary size is optimal: $BINARY_SIZE (${SIZE_MB}MB)"
+    else
+        warn "Binary size is larger than expected: $BINARY_SIZE (${SIZE_MB}MB)"
+    fi
+else
+    fail "Release binary not found"
+fi
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# Phase 3: Configuration Tests
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+print_header "Phase 3: Configuration Tests"
+
+# Test 9: Config file existence
+print_test "Configuration file check"
+CONFIG_PATH="$HOME/.zeroclaw/config.toml"
+if [ -f "$CONFIG_PATH" ]; then
+    pass "Config file exists at $CONFIG_PATH"
+
+    # Test 10: Telegram config
+    print_test "Telegram configuration check"
+    if grep -q "\[channels_config.telegram\]" "$CONFIG_PATH"; then
+        pass "Telegram configuration found"
+
+        # Test 11: Bot token configured
+        print_test "Bot token validation"
+        if grep -q "bot_token = \"" "$CONFIG_PATH"; then
+            pass "Bot token is configured"
+        else
+            warn "Bot token not set - integration tests will be skipped"
+        fi
+
+        # Test 12: Allowlist configured
+        print_test "User allowlist validation"
+        if grep -q "allowed_users = \[" "$CONFIG_PATH"; then
+            pass "User allowlist is configured"
+        else
+            warn "User allowlist not set"
+        fi
+    else
+        warn "Telegram not configured - run 'zeroclaw onboard' first"
+    fi
+else
+    warn "No config file found - run 'zeroclaw onboard' first"
+fi
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# Phase 4: Health Check Tests
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+print_header "Phase 4: Health Check Tests"
+
+# Test 13: Health check timeout
+print_test "Health check timeout (should complete in <5s)"
+START_TIME=$(date +%s)
+HEALTH_OUTPUT=$(timeout 10 target/release/zeroclaw channel doctor 2>&1 || true)
+END_TIME=$(date +%s)
+HEALTH_TIME=$((END_TIME - START_TIME))
+
+if [ $HEALTH_TIME -le 6 ]; then
+    pass "Health check completed in ${HEALTH_TIME}s (timeout fix working)"
+else
+    warn "Health check took ${HEALTH_TIME}s (expected <5s)"
+fi
+
+# Test 14: Telegram connectivity
+print_test "Telegram API connectivity"
+if echo "$HEALTH_OUTPUT" | grep -q "Telegram.*healthy"; then
+    pass "Telegram channel is healthy"
+elif echo "$HEALTH_OUTPUT" | grep -q "Telegram.*unhealthy"; then
+    warn "Telegram channel is unhealthy - check bot token"
+elif echo "$HEALTH_OUTPUT" | grep -q "Telegram.*timed out"; then
+    warn "Telegram health check timed out - network issue?"
+else
+    warn "Could not determine Telegram health status"
+fi
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# Phase 5: Feature Validation Tests
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+print_header "Phase 5: Feature Validation Tests"
+
+# Test 15: Message splitting function exists
+print_test "Message splitting function implementation"
+if grep -q "fn split_message_for_telegram" src/channels/telegram.rs; then
+    pass "Message splitting function implemented"
+else
+    fail "Message splitting function not found"
+fi
+
+# Test 16: Message length constant
+print_test "Telegram message length constant"
+if grep -q "const TELEGRAM_MAX_MESSAGE_LENGTH: usize = 4096" src/channels/telegram.rs; then
+    pass "TELEGRAM_MAX_MESSAGE_LENGTH constant defined correctly"
+else
+    fail "Message length constant missing or incorrect"
+fi
+
+# Test 17: Timeout implementation
+print_test "Health check timeout implementation"
+if grep -q "tokio::time::timeout" src/channels/telegram.rs; then
+    pass "Timeout mechanism implemented in health_check"
+else
+    fail "Timeout not implemented in health_check"
+fi
+
+# Test 18: chat_id validation
+print_test "chat_id validation implementation"
+if grep -q "let Some(chat_id) = chat_id else" src/channels/telegram.rs; then
+    pass "chat_id validation implemented"
+else
+    fail "chat_id validation missing"
+fi
+
+# Test 19: Duration import
+print_test "std::time::Duration import"
+if grep -q "use std::time::Duration" src/channels/telegram.rs; then
+    pass "Duration import added"
+else
+    fail "Duration import missing"
+fi
+
+# Test 20: Continuation markers
+print_test "Multi-part message markers"
+if grep -q "(continues...)" src/channels/telegram.rs && grep -q "(continued)" src/channels/telegram.rs; then
+    pass "Continuation markers implemented for split messages"
+else
+    fail "Continuation markers missing"
+fi
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# Phase 6: Integration Test Preparation
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+print_header "Phase 6: Manual Integration Tests"
+
+echo -e "${BLUE}The following tests require manual interaction:${NC}\n"
+
+cat << 'EOF'
+📱 Manual Test Checklist:
+
+1. [ ] Start the channel:
+   zeroclaw channel start
+
+2. [ ] Send a short message to your bot in Telegram:
+   "Hello bot!"
+   ✓ Verify: Bot responds within 3 seconds
+
+3. [ ] Send a long message (>4096 characters):
+   python3 -c 'print("test " * 1000)'
+   ✓ Verify: Message is split into chunks
+   ✓ Verify: Chunks have (continues...) and (continued) markers
+   ✓ Verify: All chunks arrive in order
+
+4. [ ] Test unauthorized access:
+   - Edit config: allowed_users = ["999999999"]
+   - Send a message
+   ✓ Verify: Warning log appears
+   ✓ Verify: Message is ignored
+   - Restore correct user ID
+
+5. [ ] Test rapid messages (10 messages in 5 seconds):
+   ✓ Verify: All messages are processed
+   ✓ Verify: No rate limit errors
+   ✓ Verify: Responses have delays
+
+6. [ ] Check logs for errors:
+   RUST_LOG=debug zeroclaw channel start
+   ✓ Verify: No unexpected errors
+   ✓ Verify: "missing chat_id" appears for malformed messages
+   ✓ Verify: Health check logs show "timed out" if needed
+
+EOF
+
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+# Test Summary
+# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+print_header "Test Summary"
+
+echo -e "${BLUE}Total Tests:${NC}   $TOTAL_TESTS"
+echo -e "${GREEN}Passed:${NC}        $PASSED_TESTS"
+echo -e "${RED}Failed:${NC}        $FAILED_TESTS"
+echo -e "${YELLOW}Warnings:${NC}      $((TOTAL_TESTS - PASSED_TESTS - FAILED_TESTS))"
+
+PASS_RATE=$((PASSED_TESTS * 100 / TOTAL_TESTS))
+echo -e "\n${BLUE}Pass Rate:${NC}     ${PASS_RATE}%"
+
+if [ $FAILED_TESTS -eq 0 ]; then
+    echo -e "\n${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+    echo -e "${GREEN}✓ ALL AUTOMATED TESTS PASSED! 🎉${NC}"
+    echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}\n"
+
+    echo -e "${BLUE}Next Steps:${NC}"
+    echo -e "1. Run manual integration tests (see checklist above)"
+    echo -e "2. Deploy to production when ready"
+    echo -e "3. Monitor logs for issues\n"
+
+    exit 0
+else
+    echo -e "\n${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+    echo -e "${RED}✗ SOME TESTS FAILED${NC}"
+    echo -e "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}\n"
+
+    echo -e "${BLUE}Troubleshooting:${NC}"
+    echo -e "1. Review failed tests above"
+    echo -e "2. Run: cargo test telegram --lib -- --nocapture"
+    echo -e "3. Check: cargo clippy --all-targets"
+    echo -e "4. Fix issues and re-run this script\n"
+
+    exit 1
+fi