feat(tts): implement TTS cache size limit and eviction policy

.env.example

@@ -189,6 +189,7 @@ SEARXNG_INSTANCE=http://localhost:8080
 # ODYSSEUS_EMAIL_COMPOSE_UPLOAD_MAX_BYTES=26214400       # email compose attachment (25 MB)
 # ODYSSEUS_STT_MAX_AUDIO_BYTES=26214400                  # speech-to-text audio (25 MB)
 # ODYSSEUS_ICS_MAX_BYTES=10485760                        # calendar .ics import (10 MB)
+# ODYSSEUS_TTS_CACHE_MAX_BYTES=52428800                  # TTS cache (500 MB)
 
 # ============================================================
 # Host Docker access (explicit opt-in)

services/tts/tts_service.py

@@ -2,6 +2,7 @@
 """Multi-provider TTS service — dispatches to local Kokoro, OpenAI-compatible API, or browser."""
 
 import io
+import os
 import wave
 import logging
 import hashlib
@@ -41,6 +42,11 @@ class TTSService:
         self.cache_dir = Path(cache_dir)
         self.cache_dir.mkdir(parents=True, exist_ok=True)
         self._kokoro = None  # lazy-init
+        
+        try:
+            self.max_cache_bytes = int(os.getenv("ODYSSEUS_TTS_CACHE_MAX_BYTES", 500 * 1024 * 1024))
+        except ValueError:
+            self.max_cache_bytes = 500 * 1024 * 1024
 
     # ── Settings ──
 
@@ -89,6 +95,35 @@ class TTSService:
         ext = ".mp3" if (len(data) >= 3 and (data[:3] == b'ID3' or (data[0] == 0xff and (data[1] & 0xe0) == 0xe0))) else ".wav"
         (self.cache_dir / f"{key}{ext}").write_bytes(data)
 
+        self._enforce_cache_limit()
+
+    def _enforce_cache_limit(self):
+        """Evicts oldest files if the cache exceeds the configured byte limit."""
+        if self.max_cache_bytes <= 0:
+            return
+
+        files = [f for f in self.cache_dir.glob("*.*") if f.is_file()]
+        total_size = sum(f.stat().st_size for f in files)
+
+        if total_size > self.max_cache_bytes:
+            logger.info(f"TTS cache ({total_size} bytes) exceeded limit ({self.max_cache_bytes} bytes). Evicting oldest files.")
+            
+            # Sort files by modification time (oldest first)
+            files.sort(key=lambda f: f.stat().st_mtime)
+            
+            # Trim down to 80% of max capacity so we aren't constantly triggering this on every new generation
+            target_size = self.max_cache_bytes * 0.8
+            
+            while files and total_size > target_size:
+                f = files.pop(0)
+                try:
+                    size = f.stat().st_size
+                    f.unlink()
+                    total_size -= size
+                except FileNotFoundError:
+                    # File was deleted by another process
+                    continue
+
     def clear_cache(self):
         count = 0
         for f in self.cache_dir.glob("*.*"):

tests/test_tts_service_enforce_cache_limit.py

@@ -0,0 +1,73 @@
+import os
+import time
+from pathlib import Path
+import pytest
+
+# Adjust the import path if your file is directly in ./services instead of ./services/tts
+from services.tts.tts_service import TTSService
+
+def test_cache_under_limit(tmp_path, monkeypatch):
+    """Test that writing a file under the size limit does not trigger eviction."""
+    # Set a tiny limit: 100 bytes
+    monkeypatch.setenv("TTS_CACHE_MAX_BYTES", "100")
+    
+    # Initialize service with pytest's temporary directory
+    service = TTSService(cache_dir=str(tmp_path))
+    
+    # Write a 40-byte file (under the 100-byte limit)
+    service._put_cache("test_key", b"x" * 40)
+    
+    # Verify the file was written and nothing was deleted
+    files = list(tmp_path.glob("*.*"))
+    assert len(files) == 1
+    assert sum(f.stat().st_size for f in files) == 40
+
+def test_cache_exceeds_limit_triggers_eviction(tmp_path, monkeypatch):
+    """Test that exceeding the limit evicts the oldest files down to 80% capacity."""
+    # Set limit to 100 bytes. 80% target capacity will be 80 bytes.
+    monkeypatch.setenv("TTS_CACHE_MAX_BYTES", "100")
+    service = TTSService(cache_dir=str(tmp_path))
+    
+    # 1. Setup: Manually create two older files (40 bytes each)
+    file1 = tmp_path / "oldest.wav"
+    file2 = tmp_path / "middle.wav"
+    
+    file1.write_bytes(b"a" * 40)
+    file2.write_bytes(b"b" * 40)
+    
+    # Spoof timestamps so file1 is explicitly older than file2
+    now = time.time()
+    os.utime(file1, (now - 100, now - 100)) # 100 seconds ago
+    os.utime(file2, (now - 50, now - 50))   # 50 seconds ago
+    
+    # 2. Action: Write a 3rd file using the service method (40 bytes)
+    # Total cache is now 120 bytes, which exceeds 100.
+    # It should delete oldest (file1) to drop to 80 bytes (which matches the 80% target).
+    service._put_cache("newest", b"c" * 40)
+    
+    # 3. Assertions
+    # The newest file should exist (saved as .wav because it lacks MP3 magic bytes)
+    newest_file = tmp_path / "newest.wav"
+    
+    assert not file1.exists(), "The oldest file should have been evicted."
+    assert file2.exists(), "The middle file should still exist."
+    assert newest_file.exists(), "The newest file should have been saved."
+    
+    # Verify the final directory size is <= 80 bytes
+    total_size = sum(f.stat().st_size for f in tmp_path.glob("*.*"))
+    assert total_size <= 80
+
+def test_cache_limit_disabled(tmp_path, monkeypatch):
+    """Test that setting max bytes to 0 disables eviction."""
+    monkeypatch.setenv("TTS_CACHE_MAX_BYTES", "0")
+    service = TTSService(cache_dir=str(tmp_path))
+    
+    # Write 3 large files that would normally trigger eviction
+    service._put_cache("file1", b"x" * 1000)
+    service._put_cache("file2", b"x" * 1000)
+    service._put_cache("file3", b"x" * 1000)
+    
+    # Ensure nothing was deleted
+    files = list(tmp_path.glob("*.*"))
+    assert len(files) == 3
+    assert sum(f.stat().st_size for f in files) == 3000