feat: add cache routing alignment and usage visibility for 2.5.0

artemis/llm/cache_affinity.py

@@ -16,8 +16,18 @@ def cache_affinity_options(
     its own cache scope so background summaries do not compete with the agent.
     Set hints per call: raw models/HTTP clients may be shared by concurrent tasks.
     Explicit caller keys and headers take precedence (including underscore aliases).
+    A caller-supplied routing header also supplies a missing body key, so gateways
+    reading different key sources agree on the same affinity whenever possible.
     """
     result = dict(options or {})
+    existing = result.get("extra_headers")
+    if "prompt_cache_key" not in result and isinstance(existing, Mapping):
+        names = {name.lower(): value for name, value in existing.items()}
+        for name in ("thread-id", "thread_id", "session-id", "session_id"):
+            value = names.get(name)
+            if isinstance(value, str) and re.fullmatch(r"[-0-9A-Za-z._:]{1,128}", value):
+                result["prompt_cache_key"] = value
+                break
     engine = getattr(ctx, "data_engine", None)
     session = getattr(ctx, "exploration_id", None) or getattr(engine, "current_session_id", None)
     if isinstance(session, (str, UUID)) and str(session):
@@ -28,7 +38,6 @@ def cache_affinity_options(
     key = result.get("prompt_cache_key")
     if not isinstance(key, str) or not re.fullmatch(r"[-0-9A-Za-z._:]{1,128}", key):
         return result
-    existing = result.get("extra_headers")
     if existing is not None and not isinstance(existing, Mapping):
         return result
     headers = dict(existing or {})