From a61edf952ff9109bc4e6def4fc985a2351ecc502 Mon Sep 17 00:00:00 2001
From: vb3 <704511+vb3@users.noreply.github.com>
Date: Wed, 1 Jul 2026 08:07:41 -0700
Subject: [PATCH] fix(gateway): add cleanup_audio_cache() and wire it into
 gateway housekeeping

Adds cleanup_audio_cache() to gateway/platforms/base.py and wires it into
_start_gateway_housekeeping() in gateway/run.py, matching the existing
image/document cache cleanup pattern.

Re-implements the fix proposed in #16473, which targeted the now-deprecated
_start_cron_ticker() and has since stalled with a merge conflict against
main. _start_gateway_housekeeping()'s docstring already claimed audio
cleanup ("prunes the image/audio/document cache"); this makes the code
match it.

Co-authored-by: nftpoetrist <264138787+nftpoetrist@users.noreply.github.com>
---
 gateway/platforms/base.py         |  21 +++++
 gateway/run.py                    |  12 ++-
 tests/gateway/test_audio_cache.py | 129 ++++++++++++++++++++++++++++++
 3 files changed, 161 insertions(+), 1 deletion(-)
 create mode 100644 tests/gateway/test_audio_cache.py

diff --git a/gateway/platforms/base.py b/gateway/platforms/base.py
index a7c3ea9fa609..04d3321bf4ba 100644
--- a/gateway/platforms/base.py
+++ b/gateway/platforms/base.py
@@ -975,6 +975,27 @@ async def cache_audio_from_url(url: str, ext: str = ".ogg", retries: int = 2) ->
                 raise
 
 
+def cleanup_audio_cache(max_age_hours: int = 24) -> int:
+    """
+    Delete cached audio files older than *max_age_hours*.
+
+    Returns the number of files removed.
+    """
+    import time
+
+    cache_dir = get_audio_cache_dir()
+    cutoff = time.time() - (max_age_hours * 3600)
+    removed = 0
+    for f in cache_dir.iterdir():
+        if f.is_file() and f.stat().st_mtime < cutoff:
+            try:
+                f.unlink()
+                removed += 1
+            except OSError:
+                pass
+    return removed
+
+
 # ---------------------------------------------------------------------------
 # Video cache utilities
 #
diff --git a/gateway/run.py b/gateway/run.py
index a4e0d613f24d..d53b2f07382f 100644
--- a/gateway/run.py
+++ b/gateway/run.py
@@ -24091,7 +24091,11 @@ def _start_gateway_housekeeping(stop_event: threading.Event, adapters=None, loop
     hour, and polls the curator hourly (its inner gate enforces the real
     weekly cadence).
     """
-    from gateway.platforms.base import cleanup_image_cache, cleanup_document_cache
+    from gateway.platforms.base import (
+        cleanup_audio_cache,
+        cleanup_document_cache,
+        cleanup_image_cache,
+    )
     from hermes_cli.debug import _sweep_expired_pastes
 
     IMAGE_CACHE_EVERY = 60   # ticks — once per hour at default 60s interval
@@ -24136,6 +24140,12 @@ def _start_gateway_housekeeping(stop_event: threading.Event, adapters=None, loop
                     logger.info("Document cache cleanup: removed %d stale file(s)", removed)
             except Exception as e:
                 logger.debug("Document cache cleanup error: %s", e)
+            try:
+                removed = cleanup_audio_cache(max_age_hours=24)
+                if removed:
+                    logger.info("Audio cache cleanup: removed %d stale file(s)", removed)
+            except Exception as e:
+                logger.debug("Audio cache cleanup error: %s", e)
 
         if tick_count % PASTE_SWEEP_EVERY == 0:
             try:
diff --git a/tests/gateway/test_audio_cache.py b/tests/gateway/test_audio_cache.py
new file mode 100644
index 000000000000..59bf505fb362
--- /dev/null
+++ b/tests/gateway/test_audio_cache.py
@@ -0,0 +1,129 @@
+"""
+Tests for audio cache utilities in gateway/platforms/base.py.
+
+Covers: get_audio_cache_dir, cache_audio_from_bytes, cleanup_audio_cache.
+"""
+
+import os
+import time
+from pathlib import Path
+
+import pytest
+
+from gateway.platforms.base import (
+    cache_audio_from_bytes,
+    cleanup_audio_cache,
+    get_audio_cache_dir,
+)
+
+# ---------------------------------------------------------------------------
+# Fixture: redirect AUDIO_CACHE_DIR to a temp directory for every test
+# ---------------------------------------------------------------------------
+
+@pytest.fixture(autouse=True)
+def _redirect_cache(tmp_path, monkeypatch):
+    """Point the module-level AUDIO_CACHE_DIR to a fresh tmp_path."""
+    monkeypatch.setattr(
+        "gateway.platforms.base.AUDIO_CACHE_DIR", tmp_path / "audio_cache"
+    )
+
+
+# ---------------------------------------------------------------------------
+# TestGetAudioCacheDir
+# ---------------------------------------------------------------------------
+
+class TestGetAudioCacheDir:
+    def test_creates_directory(self):
+        cache_dir = get_audio_cache_dir()
+        assert cache_dir.exists()
+        assert cache_dir.is_dir()
+
+    def test_returns_existing_directory(self):
+        first = get_audio_cache_dir()
+        second = get_audio_cache_dir()
+        assert first == second
+        assert first.exists()
+
+
+# ---------------------------------------------------------------------------
+# TestCacheAudioFromBytes
+# ---------------------------------------------------------------------------
+
+class TestCacheAudioFromBytes:
+    def test_basic_caching(self):
+        data = b"fake-ogg-bytes"
+        path = cache_audio_from_bytes(data)
+        assert os.path.exists(path)
+        assert Path(path).read_bytes() == data
+
+    def test_default_extension(self):
+        path = cache_audio_from_bytes(b"data")
+        assert path.endswith(".ogg")
+
+    def test_custom_extension(self):
+        path = cache_audio_from_bytes(b"data", ext=".mp3")
+        assert path.endswith(".mp3")
+
+    def test_unique_filenames(self):
+        p1 = cache_audio_from_bytes(b"a")
+        p2 = cache_audio_from_bytes(b"b")
+        assert p1 != p2
+
+    def test_file_written_inside_cache_dir(self):
+        path = cache_audio_from_bytes(b"data")
+        cache_dir = get_audio_cache_dir()
+        assert Path(path).resolve().is_relative_to(cache_dir.resolve())
+
+
+# ---------------------------------------------------------------------------
+# TestCleanupAudioCache
+# ---------------------------------------------------------------------------
+
+class TestCleanupAudioCache:
+    def test_removes_old_files(self):
+        cache_dir = get_audio_cache_dir()
+        old_file = cache_dir / "old.ogg"
+        old_file.write_text("old")
+        # Set modification time to 48 hours ago
+        old_mtime = time.time() - 48 * 3600
+        os.utime(old_file, (old_mtime, old_mtime))
+
+        removed = cleanup_audio_cache(max_age_hours=24)
+        assert removed == 1
+        assert not old_file.exists()
+
+    def test_keeps_recent_files(self):
+        cache_dir = get_audio_cache_dir()
+        recent = cache_dir / "recent.ogg"
+        recent.write_text("fresh")
+
+        removed = cleanup_audio_cache(max_age_hours=24)
+        assert removed == 0
+        assert recent.exists()
+
+    def test_returns_removed_count(self):
+        cache_dir = get_audio_cache_dir()
+        old_time = time.time() - 48 * 3600
+        for i in range(3):
+            f = cache_dir / f"old_{i}.ogg"
+            f.write_text("old")
+            os.utime(f, (old_time, old_time))
+
+        removed = cleanup_audio_cache(max_age_hours=24)
+        assert removed == 3
+
+    def test_ignores_subdirectories(self):
+        cache_dir = get_audio_cache_dir()
+        subdir = cache_dir / "subdir"
+        subdir.mkdir()
+        old_time = time.time() - 48 * 3600
+        os.utime(subdir, (old_time, old_time))
+
+        # Should not raise or attempt to remove the directory as a file.
+        removed = cleanup_audio_cache(max_age_hours=24)
+        assert removed == 0
+        assert subdir.exists()
+
+    def test_empty_cache_returns_zero(self):
+        removed = cleanup_audio_cache(max_age_hours=24)
+        assert removed == 0