superlocalmemory 3.6.1 → 3.6.3

package/CHANGELOG.md

@@ -5,6 +5,178 @@ All notable changes to SuperLocalMemory V3 will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.6.3] - 2026-06-08 — Cache + compression now work for Claude Code, Claude Desktop, Codex CLI
+
+### Fixed
+
+- **CRITICAL — Cache permanently bypassed for ALL tool-bearing clients (Claude Code, Claude Desktop, Codex CLI):**
+  `anthropic_surface.py` and `openai_surface.py` both wrapped every cache operation with
+  `if not has_tools and proxy.hooks.cache:`. Because Claude Code ALWAYS sends a `tools` array,
+  caching was structurally impossible — zero savings regardless of how many identical prompts
+  were sent. Fix: removed all four `has_tools` guards across both surfaces. Cache now fires
+  unconditionally for every request on both streaming and non-streaming paths.
+
+- **CRITICAL — Anthropic streaming SSE parser returned `None` for tool_use responses:**
+  `_parse_sse_to_json()` only accumulated `text_delta` events. Any response containing a
+  `tool_use` content block (every Claude Code response) caused the parser to emit an empty
+  content array and return `None`, meaning the completed SSE stream was never stored even if the
+  `has_tools` guard had been removed. Full rewrite: the parser now tracks content blocks by
+  index, handles both `text_delta` and `input_json_delta` events, and assembles complete
+  `tool_use` entries (with `id`, `name`, `input` JSON object) in the stored JSON. Returns
+  `None` only on genuinely incomplete streams (missing `message_start` or `message_stop`).
+
+- **CRITICAL — Anthropic SSE cache replay did not emit tool_use blocks:**
+  `_sse_from_cached_json()` only replayed `text` content blocks. Tool-use blocks were silently
+  dropped, producing a truncated response on cache hits. Fixed: the replay function now handles
+  `tool_use` blocks — emits `content_block_start` with `{type:"tool_use", id, name, input:{}}`,
+  then `input_json_delta` chunks (50-char pieces), then `content_block_stop`. Clients receive
+  a byte-for-byte equivalent of the original SSE stream.
+
+- **CRITICAL — OpenAI SSE parser returned `None` for tool_calls responses:**
+  `_parse_openai_sse_to_json()` detected `tool_calls` in the delta and returned `None`
+  immediately. OpenAI-compatible clients (Codex CLI, Antigravity) were therefore never cached.
+  Fixed: parser now accumulates `tool_calls` by `choice_index → tc_index → {id, type, function}`
+  and stores them in the assembled `chat.completion` JSON. Tool call arguments are joined from
+  streaming `arguments` deltas.
+
+- **CRITICAL — OpenAI SSE cache replay dropped tool_calls entirely:**
+  `_openai_sse_from_cached_json()` only replayed text content. Tool calls were silently dropped.
+  Fixed: replays `tool_calls` as proper OpenAI SSE delta events — first chunk with role +
+  tool_call headers (id, type, name, empty arguments), then argument chunks (50-char pieces),
+  then finish chunk. Preserves the streaming contract with clients.
+
+- **CompressRouter never instantiated — `compress_hook=None` always:**
+  `_load_hooks()` in `server.py` had dead code: `if config.compress_enabled: pass`. The
+  `CompressRouter` singleton was never created, so compression was silently a no-op for every
+  session since v3.6.0. Fixed: `_load_hooks()` now calls `CompressRouter.get_instance()` and
+  wires it into the `HookChain`. Daemon log now correctly reports `compress_hook=CompressRouter`.
+
+- **MetricsCollector never wired to CompressRouter — `compress_runs=0` always:**
+  `CompressRouter.set_metrics()` was never called during proxy startup, so
+  `_metrics_counters=None` permanently. Result: `compress_runs` counter was always 0 in the
+  dashboard even when compression was running. Fixed: `_load_hooks()` calls
+  `compress_hook.set_metrics(MetricsCollector.get_instance())` immediately after instantiation.
+
+- **`on_compress` signature mismatch — metrics counter never incremented:**
+  `CompressRouter._compress_messages()` called `self._metrics_counters.on_compress(saved, lossy)`
+  where `saved` was bytes-saved and `lossy` was a bool. `MetricsCollector.on_compress()` expects
+  `(bytes_original, bytes_after)`. The mismatch meant `compress_runs` and `bytes_saved` were
+  always wrong even after wiring. Fixed: caller now passes `(before_tokens, after_tokens)`.
+
+- **`is_tool_msg` in `CompressRouter` skipped ALL user messages from compression:**
+  The original guard was `is_tool_msg = (role == "tool" or role == "user")`. This silently
+  skipped every `user` turn, including long tool-result messages (the main source of savings
+  in Claude Code sessions). Fixed: only OpenAI `role=="tool"` messages are skipped. Anthropic
+  `tool_result` blocks (embedded in user message content arrays) are now compressed by
+  `_compress_content_block()`, which handles the nested structure correctly.
+
+### Tests
+
+- `tests/optimize/proxy/test_openai_surface.py`: updated `test_parse_openai_sse_to_json_tool_calls_returns_none`
+  → renamed to `test_parse_openai_sse_to_json_tool_calls_cached`, asserts valid JSON returned
+  with `tool_calls` array preserved instead of `None`.
+- `tests/optimize/proxy/test_server.py`: updated `test_load_hooks_compress_enabled_placeholder`
+  → renamed to `test_load_hooks_compress_enabled_loads_router`, asserts `hooks.compress is not None`
+  and `isinstance(hooks.compress, CompressRouter)`.
+- All 83 proxy tests pass (0 failures).
+
+### Documentation
+
+- `docs/proxy-setup.md`: removed "Cache fires only for requests WITHOUT tools" caveat. Updated
+  "What Gets Cached" table — Claude Code, Claude Desktop, Codex CLI now show `✓ Yes`. Added
+  explanation of how tool-use caching works (SSE accumulate → parse → store → replay as SSE).
+  Updated troubleshooting section — removed stale "tool-bearing requests are bypassed" note,
+  added actionable checklist for diagnosing zero-savings scenarios.
+
+---
+
+## [3.6.3] - 2026-06-08 — Proxy streaming cache fix for Anthropic, OpenAI surfaces
+
+### Fixed
+
+- **CRITICAL — Anthropic streaming cache never populated (miss permanently 0 savings):**
+  `anthropic_surface.py`'s streaming path called `_stream_forward()` (no-op passthrough)
+  instead of the new `_stream_and_cache_forward()`. Claude Code, AGY, and every other
+  streaming Anthropic client could never populate the cache because the response body was
+  never accumulated. Cache was always empty, `tokens_saved` was always 0, regardless of how
+  many identical prompts were sent. Fix: streaming path now checks cache on the way in
+  (`_safe_cache_check`), runs compression on the request body, and passes a `store_callback`
+  to `_stream_and_cache_forward()` that accumulates the SSE stream, parses it via
+  `_parse_sse_to_json`, and stores the assembled JSON message after `message_stop` is seen.
+  Second identical streaming call returns a properly re-emitted SSE stream from cache
+  (verified: `msg_id` identical, no upstream call on hit).
+
+- **CRITICAL — OpenAI streaming surface: cache bypassed + `_safe_compress` NameError:**
+  `openai_surface.py` had the same streaming bypass bug AND a missing import — `_safe_compress`
+  was called on the non-streaming compression path but never imported, causing a silent
+  `NameError` on any non-streaming request with compression enabled. Both issues fixed:
+  (1) streaming path now wires `_stream_and_cache_forward` with `_parse_openai_sse_to_json`
+  and `_openai_sse_from_cached_json` helpers (OpenAI SSE format differs from Anthropic's —
+  uses `[DONE]` sentinel and `chat.completion.chunk` objects). (2) `_safe_compress` added
+  to imports. Cache hit on OpenAI streaming calls now returns a re-emitted SSE stream with
+  proper `chat.completion.chunk` events and `[DONE]` terminator.
+
+- **`_stream_and_cache_forward` completion marker was Anthropic-only:**
+  The `finally` block checked for `b"message_stop"` to detect a complete stream before
+  calling `on_complete`. OpenAI SSE streams end with `data: [DONE]\n\n` — not `message_stop`.
+  Result: OpenAI streaming responses were never stored in cache even after the fix above
+  because the `on_complete` callback was never fired. Fixed by checking both markers:
+  `b"message_stop"` (Anthropic) OR `b"[DONE]"` (OpenAI / any compatible provider).
+
+- **`_stream_and_cache_forward` redundant join:** `full = b"".join(acc)` recomputed the
+  join that `_joined` had already computed. Fixed to reuse `_joined` directly.
+
+- **`server.py` version string stuck at `"3.6.0"`:** `_PROXY_VERSION` was not updated
+  during the 3.6.1 and 3.6.2 releases. Fixed to `"3.6.3"`. The `/health` endpoint now
+  correctly reports `"version":"3.6.3"`.
+
+- **`CacheManager.get()` returned `None` on miss, discarding the cache key:** Store
+  condition `cache_result.cache_key` was always falsy on miss because `get()` returned
+  `None` (no `CachedResponse` object). Non-streaming responses after a miss were never
+  stored. Fixed: `get()` now returns `CachedResponse(hit=False, data=None, cache_key=key)`
+  so the key propagates to the store condition.
+
+- **`CacheManager.check()` never called `MetricsCollector.on_miss()`:** Miss events were
+  not counted, so `hits/(hits+misses)` was always 0 in the dashboard. Fixed: `check()`
+  calls `MetricsCollector.get_instance().on_miss()` when `result.hit is False`.
+
+### Added
+
+- `_parse_openai_sse_to_json(sse_bytes)`: assembles OpenAI streaming chunks into a
+  single `chat.completion` JSON for cache storage. Handles multi-index choices, usage
+  capture, `tool_calls` detection (never caches tool responses), and `[DONE]` sentinel.
+- `_openai_sse_from_cached_json(cached_bytes)`: replays a stored `chat.completion` as
+  a proper OpenAI SSE stream for cache-hit responses. Emits role chunk, content chunks
+  (100-char batches), finish chunk, and `[DONE]`. Preserves the streaming contract with
+  clients (Codex CLI, Antigravity, openai-python).
+- `docs/proxy-setup.md`: comprehensive per-CLI proxy activation guide covering Claude Code
+  CLI, Claude Desktop, Cursor, Windsurf, AGY/Antigravity, Gemini CLI, Codex CLI, Python
+  anthropic/openai SDK, Node.js SDK, LangChain, LlamaIndex, SDK adapter, and raw curl.
+  Includes an honest "What Gets Cached" table showing which clients benefit from caching.
+
+### Tests
+
+- `tests/optimize/proxy/test_openai_surface.py`: 9 new tests covering
+  `_parse_openai_sse_to_json` (complete stream, missing `[DONE]`, tool calls, empty bytes,
+  usage capture) and `_openai_sse_from_cached_json` (roundtrip, bad JSON, wrong object
+  type) plus an end-to-end streaming cache miss→store→hit cycle.
+- All 583 optimize tests pass (4 skipped — platform-specific).
+
+---
+
+## [3.6.2] - 2026-06-08 — wrap dry_run fix for config-file mechanism (macOS CI)
+
+### Fixed
+- **`slm wrap` `config-file` dry_run fails on machines without VS Code installed:** `wrap_agent()`
+  with `mechanism="config-file"` called `_vscode_user_dir()` before the `if dry_run: return 0`
+  guard. On CI runners (and any machine without VS Code), `_vscode_user_dir()` returns `None`,
+  causing the function to return 1 with "[slm wrap] VS Code user dir not found" even for
+  `dry_run=True` calls that never need the path to exist. Fix: moved `if dry_run: return 0`
+  to before the `_vscode_user_dir()` lookup — consistent with the same pattern already applied
+  to the `env` mechanism in v3.6.1.
+
+---
+
 ## [3.6.1] - 2026-06-07 — Optimize module fixes: proxy liveness probe, UI tab init, PyPI CI unblock
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superlocalmemory",
-  "version": "3.6.1",
+  "version": "3.6.3",
   "description": "Information-geometric agent memory with mathematical guarantees. 4-channel retrieval, Fisher-Rao similarity, zero-LLM mode, EU AI Act compliant. Works with Claude, Cursor, Windsurf, and 17+ AI tools.",
   "keywords": [
     "ai-memory",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superlocalmemory"
-version = "3.6.1"
+version = "3.6.3"
 description = "Information-geometric agent memory with mathematical guarantees"
 readme = "README.md"
 license = {text = "AGPL-3.0-or-later"}

package/src/superlocalmemory/__init__.py

@@ -28,7 +28,7 @@ if "OMP_NUM_THREADS" not in os.environ:
     os.environ["OMP_NUM_THREADS"] = "2"
 # ---------------------------------------------------------------------------
 
-__version__ = "3.6.1"
+__version__ = "3.6.3"
 
 _REQUIRED_VERSIONS = {
     "sentence_transformers": "5.3.0",

package/src/superlocalmemory/optimize/adapters/wrap.py

@@ -21,10 +21,19 @@ _STATIC_MECHANISMS = {"settings-file", "config-file", "print-only"}
 
 
 def _proxy_configured() -> bool:
-    """Return True if proxy_enabled=True in optimize.json (no liveness check)."""
+    """Return True if proxy_enabled=True in optimize.json (no liveness check).
+
+    Reads from the module-level _store if it has been set (daemon process or
+    tests that call _set_config_store). Falls back to a fresh ConfigStore read
+    from disk when _store is None — which is always the case in CLI subprocess
+    context because _set_config_store() is only called by the daemon on startup.
+    """
     try:
-        from superlocalmemory.optimize.config import get_optimize_config
-        return get_optimize_config().proxy_enabled
+        from superlocalmemory.optimize.config import _store
+        if _store is not None:
+            return _store.get().proxy_enabled
+        from superlocalmemory.optimize.config.store import ConfigStore
+        return ConfigStore().get().proxy_enabled
     except Exception:
         return False
 
@@ -130,6 +139,10 @@ def wrap_agent(
         if not config_path_str:
             print("[slm wrap] no config_path specified", file=sys.stderr)
             return 1
+        # dry_run: show intent without requiring VS Code to be installed.
+        if dry_run:
+            print(f"[slm wrap] would write {config_path_str} key={config_key} value={config_value}")
+            return 0
         if "{vscode_user_dir}" in config_path_str:
             vscode_dir = _vscode_user_dir()
             if vscode_dir is None:
@@ -138,9 +151,6 @@ def wrap_agent(
             path = Path(config_path_str.replace("{vscode_user_dir}", str(vscode_dir)))
         else:
             path = Path(config_path_str).expanduser()
-        if dry_run:
-            print(f"[slm wrap] would write {path} key={config_key} value={config_value}")
-            return 0
         existing = {}
         if path.exists():
             try:

package/src/superlocalmemory/optimize/cache/manager.py

@@ -153,9 +153,42 @@ class CacheManager:
     # ---- INTERFACE-CONTRACT §4 public methods ----
 
     def build_key(self, req: Any, tenant_id: str) -> str | None:
-        """Build a deterministic cache key for req + tenant_id."""
-        if isinstance(req, dict):
-            model_id = req.get("model", "")
+        """Build a deterministic cache key for req + tenant_id.
+
+        BUG-FIX (v3.6.3): Two bugs repaired here:
+        1. tenant_id="default" failed KeyBuilder's 64-char hex SHA-256 validation,
+           silently raising ValueError caught by fail-open wrappers → cache never
+           stored or retrieved anything via the proxy path. Fix: normalize any
+           non-hex tenant_id to its SHA-256 digest before passing to KeyBuilder.
+        2. ProxyRequest objects have a `body` dict, not model_id/messages/system
+           attributes. The old `getattr(req, "model_id", "")` path silently
+           returned empty strings → all proxy requests got the same (invalid) key.
+           Fix: detect ProxyRequest and extract fields from .body.
+        """
+        import hashlib as _hashlib
+        import json as _json
+        import re as _re
+        _HEX64 = _re.compile(r"[0-9a-f]{64}")
+        # Normalize tenant_id: KeyBuilder requires a 64-char lowercase hex SHA-256.
+        if not _HEX64.fullmatch(tenant_id or ""):
+            tenant_id = _hashlib.sha256(tenant_id.encode()).hexdigest()
+
+        if isinstance(req, ProxyRequest):
+            # Extract semantic fields from the parsed JSON body.
+            body = req.body or {}
+            model_id = body.get("model", "") or ""
+            messages = body.get("messages", []) or []
+            system_raw = body.get("system", "") or ""
+            # Anthropic allows system as a list of content blocks — normalise to str.
+            if isinstance(system_raw, list):
+                system = _json.dumps(system_raw, sort_keys=True, separators=(",", ":"))
+            else:
+                system = str(system_raw)
+            # params: everything except fields extracted above and stream flag.
+            _SKIP = frozenset({"model", "messages", "system", "stream"})
+            params = {k: v for k, v in body.items() if k not in _SKIP}
+        elif isinstance(req, dict):
+            model_id = req.get("model", "") or ""
             messages = req.get("messages", []) or []
             params = req.get("params", {}) or {}
             system = req.get("system", "") or ""
@@ -174,9 +207,18 @@ class CacheManager:
         )
 
     def get(self, req: Any, tenant_id: str) -> "CachedResponse | None":
-        """CacheHook.check() entry point."""
+        """CacheHook.check() entry point.
+
+        BUG-FIX (v3.6.3): Previously returned None on cache miss, which caused
+        _safe_cache_check to return CachedResponse(cache_key="").  The empty
+        cache_key is falsy, so the store condition in handle_messages
+        (``cache_result.cache_key``) was always False → cache was NEVER
+        populated.  Fix: return a miss CachedResponse that carries the computed
+        key so the store path can proceed.
+        """
         key = self.build_key(req, tenant_id)
         if key is None:
+            # Uncacheable (non-zero temperature, etc.) — signal with None.
             return None
         row = self._exact.get(key, tenant_id)
         if row is not None:
@@ -188,7 +230,8 @@ class CacheManager:
                 ttl_seconds=0,
             )
         self._metrics.exact_misses += 1
-        return None
+        # Return miss WITH the key so callers can use it for cache storage.
+        return CachedResponse(hit=False, data=None, cache_key=key, ttl_seconds=0)
 
     def set(self, req: Any, resp: Any, tenant_id: str) -> None:
         """CacheHook.store() entry point."""
@@ -196,8 +239,10 @@ class CacheManager:
         key = self.build_key(req, tenant_id)
         if key is None:
             return
-        if isinstance(req, dict):
-            model_id = req.get("model", "")
+        if isinstance(req, ProxyRequest):
+            model_id = (req.body or {}).get("model", "") or ""
+        elif isinstance(req, dict):
+            model_id = req.get("model", "") or ""
         else:
             model_id = getattr(req, "model_id", "") or ""
         tags = [
@@ -216,9 +261,18 @@ class CacheManager:
     # ---- CacheHook protocol implementation (INTERFACE-CONTRACT §3) ----
 
     def check(self, req: ProxyRequest) -> "CachedResponse | None":
-        """CacheHook.check() — look up by ProxyRequest; fail-open on error."""
+        """CacheHook.check() — look up by ProxyRequest; fail-open on error.
+
+        BUG-FIX (v3.6.3): on_miss() was never called from the proxy path,
+        so MetricsCollector.misses stayed at 0 and the dashboard always showed
+        0 misses.  Fixed by calling on_miss() here whenever get() returns a
+        cache-miss result.
+        """
         try:
-            return self.get(req, tenant_id="default")
+            result = self.get(req, tenant_id="default")
+            if result is not None and not result.hit:
+                MetricsCollector.get_instance().on_miss()
+            return result
         except Exception as exc:
             logger.warning("CacheManager.check raised (fail-open): %s", exc)
             return None

package/src/superlocalmemory/optimize/compress/router.py

@@ -71,10 +71,6 @@ class CompressRouter:
 
             if not cfg.compress_enabled:
                 return req
-            if req.stream:
-                return req
-            if req.has_tools:
-                return req  # §6.5 safety rule
 
             body = dict(req.body)
             messages = body.get("messages", [])
@@ -139,8 +135,8 @@ class CompressRouter:
         try:
             saved = max(0, before_tokens - after_tokens)
             if self._metrics_counters is not None:
-                # M-02: Call proper method instead of accessing private attribute
-                self._metrics_counters.on_compress(saved, lossy)
+                # M-02: pass before/after directly (bytes_original, bytes_after contract)
+                self._metrics_counters.on_compress(before_tokens, after_tokens)
             logger.debug("on_compress: saved=%d tokens lossy=%s", saved, lossy)
         except Exception as exc:
             logger.debug("on_compress metrics update failed (non-fatal): %s", exc)
@@ -169,9 +165,11 @@ class CompressRouter:
         for idx, msg in enumerate(messages):
             role = msg.get("role", "")
             is_tool_msg = (
-                role == "tool"
-                or role == "user"
-                or _msg_has_tool_result(msg)
+                role == "tool"  # OpenAI tool result messages (plain text, skip entirely)
+                # Anthropic tool_result blocks are NOT skipped — _compress_content_block
+                # handles type=="tool_result" blocks by compressing their text content
+                # while preserving the block structure. This is where the bulk of
+                # Claude Code output lives (bash results, file contents, JSON data).
             )
             if idx in protect_indices or is_tool_msg:
                 new_messages.append(msg)

package/src/superlocalmemory/optimize/proxy/_helpers.py

@@ -3,8 +3,9 @@
 from __future__ import annotations
 
 import asyncio
+import json
 import logging
-from typing import Any, AsyncIterator
+from typing import Any, AsyncIterator, Callable
 
 import httpx
 from fastapi.requests import Request
@@ -121,6 +122,143 @@ def _filter_response_headers(headers) -> dict:
     return {k: v for k, v in items if k.lower() not in _HOP_BY_HOP}
 
 
+# ---------------------------------------------------------------------------
+# SSE → JSON converter (for streaming cache hits and post-stream storage)
+# ---------------------------------------------------------------------------
+
+def _parse_sse_to_json(sse_bytes: bytes) -> bytes | None:
+    """Parse an accumulated Anthropic SSE stream into a single JSON message.
+
+    Used for two purposes:
+    1. After a streaming response completes — store the assembled JSON in the
+       cache so the next identical streaming request is served from cache.
+    2. Cache hit path — convert stored JSON back to SSE via _sse_from_cached_json
+       in anthropic_surface.py.
+
+    Returns None if the bytes are not a valid/complete Anthropic SSE stream
+    (e.g. error response, client-disconnected partial, or empty). The caller
+    MUST treat None as "do not cache".
+
+    BUG-FIX (v3.6.4): Previously returned None for any response containing
+    tool_use blocks, which meant Claude Code responses were NEVER cached (Claude
+    Code always uses tools). Now handles both text AND tool_use content blocks:
+    - text blocks: accumulated via text_delta events
+    - tool_use blocks: accumulated via input_json_delta events, stored with
+      full {id, name, input} so _sse_from_cached_json can replay them correctly.
+    """
+    # content_blocks[index] = {"type": "text", "text_parts": [...]} OR
+    #                          {"type": "tool_use", "id": "...", "name": "...", "input_parts": [...]}
+    content_blocks: dict[int, dict] = {}
+    message_id = ""
+    model = ""
+    role = "assistant"
+    input_tokens = 0
+    output_tokens = 0
+    stop_reason = "end_turn"
+    message_start_seen = False
+    message_stop_seen = False
+
+    current_event = ""
+    for raw_line in sse_bytes.decode("utf-8", errors="replace").split("\n"):
+        line = raw_line.rstrip("\r")
+        if line.startswith("event: "):
+            current_event = line[7:].strip()
+        elif line.startswith("data: "):
+            data_str = line[6:].strip()
+            if not data_str or data_str == "[DONE]":
+                continue
+            try:
+                data = json.loads(data_str)
+            except json.JSONDecodeError:
+                continue
+
+            if current_event == "message_start":
+                message_start_seen = True
+                msg = data.get("message", {})
+                message_id = msg.get("id", "")
+                model = msg.get("model", "")
+                role = msg.get("role", "assistant")
+                usage = msg.get("usage", {})
+                input_tokens = usage.get("input_tokens", 0)
+
+            elif current_event == "content_block_start":
+                idx = data.get("index", 0)
+                cb = data.get("content_block", {})
+                block_type = cb.get("type", "text")
+                if block_type == "tool_use":
+                    content_blocks[idx] = {
+                        "type": "tool_use",
+                        "id": cb.get("id", ""),
+                        "name": cb.get("name", ""),
+                        "input_parts": [],
+                    }
+                else:
+                    content_blocks[idx] = {"type": "text", "text_parts": []}
+
+            elif current_event == "content_block_delta":
+                idx = data.get("index", 0)
+                delta = data.get("delta", {})
+                block = content_blocks.get(idx)
+                if block is None:
+                    continue
+                delta_type = delta.get("type", "")
+                if delta_type == "text_delta":
+                    block.setdefault("text_parts", []).append(delta.get("text", ""))
+                elif delta_type == "input_json_delta":
+                    block.setdefault("input_parts", []).append(delta.get("partial_json", ""))
+
+            elif current_event == "message_delta":
+                usage2 = data.get("usage", {})
+                output_tokens = usage2.get("output_tokens", 0)
+                stop = data.get("delta", {})
+                stop_reason = stop.get("stop_reason", stop_reason) or stop_reason
+
+            elif current_event == "message_stop":
+                message_stop_seen = True
+
+    if not message_start_seen or not message_stop_seen:
+        return None
+
+    # Assemble content array — preserve block ordering by index
+    content: list[dict] = []
+    for idx in sorted(content_blocks.keys()):
+        block = content_blocks[idx]
+        if block["type"] == "tool_use":
+            input_json_str = "".join(block.get("input_parts", []))
+            try:
+                input_obj = json.loads(input_json_str) if input_json_str else {}
+            except json.JSONDecodeError:
+                input_obj = {"_raw": input_json_str}
+            content.append({
+                "type": "tool_use",
+                "id": block["id"],
+                "name": block["name"],
+                "input": input_obj,
+            })
+        else:
+            text = "".join(block.get("text_parts", []))
+            content.append({"type": "text", "text": text})
+
+    result = {
+        "id": message_id,
+        "type": "message",
+        "role": role,
+        "content": content,
+        "model": model,
+        "stop_reason": stop_reason,
+        "stop_sequence": None,
+        "usage": {
+            "input_tokens": input_tokens,
+            "output_tokens": output_tokens,
+        },
+    }
+    return json.dumps(result, separators=(",", ":")).encode("utf-8")
+
+
+# ---------------------------------------------------------------------------
+# HTTP helpers
+# ---------------------------------------------------------------------------
+
 async def _fail_open_forward(proxy: Any, request: Request, upstream_url: str) -> Response:
     if proxy.http_client is None:
         logger.error(
@@ -167,6 +305,7 @@ async def _stream_forward(
     body_bytes: bytes,
     upstream_url: str,
 ) -> Response | StreamingResponse:
+    """Simple passthrough streaming — no cache accumulation."""
     if proxy.http_client is None:
         logger.error(
             "[%s] _stream_forward: http_client is None - startup() was not called. "
@@ -212,6 +351,102 @@ async def _stream_forward(
     )
 
 
+async def _stream_and_cache_forward(
+    proxy: Any,
+    request_id: str,
+    fwd_headers: dict,
+    body_bytes: bytes,
+    upstream_url: str,
+    on_complete: "Callable[[bytes], Any] | None" = None,
+) -> Response | StreamingResponse:
+    """Stream-forward with optional post-stream cache-store callback.
+
+    BUG-FIX (v3.6.3): Claude Code exclusively uses streaming.  The old
+    _stream_forward never accumulated the response body, so the cache was
+    NEVER populated — savings were permanently 0.
+
+    This helper tees the stream: each chunk is yielded to the client AND
+    appended to an in-memory accumulator.  After the LAST chunk (detected by
+    ``message_stop`` in the SSE bytes), ``on_complete`` is awaited with the
+    full accumulated bytes.  The caller converts those bytes to a JSON message
+    via ``_parse_sse_to_json`` and stores them in the cache.
+
+    on_complete is only called when:
+    - the accumulated bytes contain ``b"message_stop"`` (complete response),
+    - the response did NOT error mid-stream.
+    """
+    if proxy.http_client is None:
+        logger.error(
+            "[%s] _stream_and_cache_forward: http_client is None.",
+            request_id,
+        )
+        return Response(
+            content=b'{"type":"error","error":{"type":"api_error",'
+                    b'"message":"SLM proxy not started - lifespan wiring error"}}',
+            status_code=502,
+            media_type="application/json",
+        )
+
+    acc: list[bytes] = []
+    complete_called = False
+
+    async def _generate() -> AsyncIterator[bytes]:
+        nonlocal complete_called
+        stream_error = False
+        try:
+            async with proxy.http_client.stream(
+                "POST", upstream_url, content=body_bytes, headers=fwd_headers,
+            ) as upstream_resp:
+                async for chunk in upstream_resp.aiter_bytes():
+                    if chunk:
+                        acc.append(chunk)
+                        yield chunk
+        except httpx.RemoteProtocolError as exc:
+            stream_error = True
+            logger.warning("[%s] upstream stream closed early: %r", request_id, exc)
+            yield (
+                b'event: error\ndata: {"type":"error","error":{'
+                b'"type":"api_error","message":"upstream stream closed"}}\n\n'
+            )
+        except Exception as exc:
+            stream_error = True
+            logger.error("[%s] stream forward error: %r", request_id, exc)
+            yield (
+                b'event: error\ndata: {"type":"error","error":{'
+                b'"type":"api_error","message":"SLM proxy stream error"}}\n\n'
+            )
+        finally:
+            # BUG-FIX (v3.6.4): Removed surface-specific sentinel check
+            # ("message_stop" / "[DONE]"). Completeness is now validated
+            # inside each parser (_parse_sse_to_json, _parse_openai_sse_to_json,
+            # _parse_gemini_sse_to_json) which return None for incomplete
+            # streams. This makes _stream_and_cache_forward universal: it
+            # calls on_complete whenever the stream ends without error and
+            # lets the parser decide whether to store. Gemini SSE has neither
+            # sentinel — streams end by connection close after the final chunk
+            # containing "finishReason".
+            _joined = b"".join(acc)
+            if on_complete and acc and not complete_called and not stream_error:
+                complete_called = True
+                try:
+                    await on_complete(_joined)
+                except Exception as exc:
+                    logger.warning(
+                        "[%s] cache store callback raised (fail-open): %r",
+                        request_id, exc,
+                    )
+
+    return StreamingResponse(
+        _generate(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
 async def _safe_cache_check(hooks: HookChain, ctx: ProxyRequest) -> CachedResponse:
     try:
         result = hooks.cache.check(ctx)