@rulemetric/proxy 0.2.2

package/addon/rulemetric_addon.py

@@ -0,0 +1,1288 @@
+"""mitmproxy addon that captures LLM API requests AND responses, reporting them to RuleMetric."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import sys
+import threading
+import time
+from datetime import datetime, timezone
+
+from mitmproxy import http
+
+from providers import detect_provider, parse_anthropic, parse_openai, parse_gemini, parse_bedrock, parse_copilot_fim
+from reporter import report_snapshot, report_event
+from session_linker import find_active_session, find_session_by_external_id
+from sse_parser import parse_streaming_response
+
+logger = logging.getLogger("rulemetric.addon")
+
+# Parsers for non-OpenAI formats. Any provider not listed here
+# is assumed to be OpenAI-compatible and uses parse_openai.
+_NON_OPENAI_PARSERS = {
+    "anthropic": parse_anthropic,
+    "gemini": parse_gemini,
+    "bedrock": parse_bedrock,
+    "github_copilot_fim": parse_copilot_fim,
+}
+
+
+def _get_parser(provider: str):
+    """Return the parser for a provider, defaulting to parse_openai."""
+    return _NON_OPENAI_PARSERS.get(provider, parse_openai)
+
+
+_UUID_RE_LITERAL = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
+
+# Providers whose wire session id is strong enough (unique per conversation,
+# no aliasing risk) that the proxy is allowed to AUTO-CREATE a session row
+# on first sight, when no registry file exists.
+#
+# This is a narrow relaxation of the "never auto-create" rule from commit
+# 7aebad7. The rule existed because pre-wire-first attribution, orphan
+# sessions became magnets that swallowed unrelated traffic. With wire-first,
+# each provider's id below is per-conversation, so magnet behavior is
+# impossible — every new value lands on its own session row.
+#
+# Add a provider here ONLY after confirming its wire id is per-conversation
+# (not per-machine, per-account, etc.). Cursor is explicitly NOT here because
+# its hooks write the registry file. Anthropic was added 2026-06-11: `hooks
+# install` stopped writing Claude Code hooks (the registry writer), and the
+# anthropic wire id is the per-conversation session_id from
+# body.metadata.user_id — it satisfies the per-conversation rule, so the
+# proxy bootstraps the session row itself. If a hook DID already register
+# the wire id, the registry-file fast path wins and no duplicate is created.
+_PROVIDERS_WITH_AUTO_BOOTSTRAP = frozenset({
+    "github_copilot_chat",  # vscode-sessionid header — stable per VS Code window
+    "anthropic",            # Claude Code session_id — unique per conversation
+})
+
+# Maps internal provider name to the `tool` value used in the sessions table.
+_PROVIDER_TO_TOOL = {
+    "github_copilot_chat": "vscode_copilot",
+    "anthropic": "claude_code",
+}
+
+
+def _extract_wire_session_id(
+    provider: str,
+    body: dict | None,
+    headers: object | None = None,
+) -> str | None:
+    """Pull the harness session id off the wire if the provider embeds one.
+
+    Race-free attribution: every request from a given Claude Code / Cursor /
+    Copilot instance carries that instance's own session id. The proxy reads
+    it from the wire instead of guessing via the filesystem registry's
+    mtimes, so multiple concurrent same-tool instances never
+    cross-contaminate.
+
+    Per-provider sources:
+      * ``anthropic``: ``body.metadata.user_id`` (Claude Code packs a JSON
+        blob ``{device_id, account_uuid, session_id}`` into the field).
+      * ``github_copilot_chat``: ``vscode-sessionid`` HEADER (stable per VS
+        Code window; one RuleMetric session per VS Code instance — see
+        `_PROVIDERS_WITH_AUTO_BOOTSTRAP`).
+
+    OpenAI/Cursor put a stable user id in ``body.user``; whether it's a
+    session id or a long-lived machine id is harness-dependent, so it's an
+    opt-in fallback only and not implemented here.
+    """
+    try:
+        if provider == "anthropic":
+            if not body:
+                return None
+            md = body.get("metadata") or {}
+            raw = md.get("user_id")
+            if not raw:
+                return None
+            # Claude Code packs JSON into user_id. Older builds may send a bare
+            # uuid; tolerate both.
+            if isinstance(raw, str) and raw.startswith("{"):
+                try:
+                    parsed = json.loads(raw)
+                    sid = parsed.get("session_id") if isinstance(parsed, dict) else None
+                except json.JSONDecodeError:
+                    sid = None
+            else:
+                sid = raw if isinstance(raw, str) else None
+            if isinstance(sid, str) and re.fullmatch(_UUID_RE_LITERAL, sid):
+                return sid
+            return None
+
+        if provider == "github_copilot_chat" and headers is not None:
+            # mitmproxy.http.Headers supports .get like a dict
+            sid = headers.get("vscode-sessionid") if hasattr(headers, "get") else None
+            if isinstance(sid, str) and sid:
+                return sid
+            return None
+    except (AttributeError, TypeError):
+        # Defensive — body / headers shape may differ across SDK versions
+        return None
+    return None
+
+
+def _ensure_session_for_wire_id(
+    provider: str,
+    wire_id: str,
+    project_path: str | None = None,
+) -> str | None:
+    """Auto-create a RuleMetric session for an allowlisted wire-id provider.
+
+    Returns the DB session id on success, or None if the provider isn't
+    allowlisted or the create call fails.
+
+    On success, writes the registry file at $TMPDIR/rulemetric/<wire_id> so
+    subsequent requests with the same wire id hit the registry-file fast
+    path instead of re-bootstrapping.
+    """
+    if provider not in _PROVIDERS_WITH_AUTO_BOOTSTRAP:
+        return None
+
+    # wire_id becomes a filename below. The anthropic path is UUID-validated
+    # upstream, but copilot's vscode-sessionid header is attacker-influenced
+    # and only checked for non-emptiness — enforce the registry charset here
+    # (same rule as session_linker._EXTERNAL_ID_RE) before any write.
+    if not re.fullmatch(r"[A-Za-z0-9_.\-]{8,128}", wire_id):
+        logger.warning(
+            "auto-bootstrap rejected wire id failing charset validation (provider %s): %r",
+            provider, wire_id[:32],
+        )
+        return None
+
+    # Re-check the registry: a concurrent request may have just bootstrapped
+    info = find_session_by_external_id(wire_id)
+    if info and info.get("session_id"):
+        return info["session_id"]
+
+    # Lazy-imported to avoid widening the addon's import surface at startup
+    import urllib.error
+    import urllib.request
+    from reporter import _get_api_url, _get_auth_headers
+    from session_linker import _get_session_dir
+
+    tool = _PROVIDER_TO_TOOL.get(provider, provider)
+    # Schema: apps/api/src/routes/sessions.ts:createSessionSchema. Optional
+    # fields are `z.string().optional()` — they reject null. Only include
+    # fields we actually have a value for.
+    payload_dict: dict[str, object] = {
+        "tool": tool,
+        "externalSessionId": wire_id,
+        "metadata": {
+            "autoBootstrapped": True,
+            "viaProxy": True,
+            "provider": provider,
+        },
+    }
+    if project_path:
+        payload_dict["projectPath"] = project_path
+    payload = json.dumps(payload_dict).encode("utf-8")
+
+    req = urllib.request.Request(
+        f"{_get_api_url()}/api/sessions",
+        data=payload,
+        headers=_get_auth_headers(),
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.URLError as exc:
+        logger.warning("auto-bootstrap session POST failed for %s: %s", provider, exc)
+        return None
+    except (json.JSONDecodeError, ValueError) as exc:
+        logger.warning("auto-bootstrap session response unparseable: %s", exc)
+        return None
+
+    session_id = data.get("id") if isinstance(data, dict) else None
+    if not session_id:
+        logger.warning("auto-bootstrap response missing 'id': %s", str(data)[:200])
+        return None
+
+    # Write registry file so subsequent same-wire-id requests find it without
+    # re-POSTing.
+    try:
+        sdir = _get_session_dir()
+        sdir.mkdir(parents=True, exist_ok=True)
+        (sdir / wire_id).write_text(f"{session_id}\n{tool}\n")
+    except OSError as exc:
+        logger.warning("registry file write failed for %s: %s", wire_id[:16], exc)
+        # Not fatal — return the session id anyway; next request will retry
+
+    logger.info(
+        "Auto-bootstrapped %s session %s for wire id %s",
+        tool, session_id[:8], wire_id[:16],
+    )
+    return session_id
+
+
+# Wire ids with a bootstrap thread currently in flight — prevents a burst of
+# same-session requests from POSTing duplicate session rows before the first
+# thread writes the registry file.
+_PENDING_BOOTSTRAPS: set[str] = set()
+_PENDING_LOCK = threading.Lock()
+
+
+# Last-seen plan tier from oauth/account/settings (dict so tests can reset).
+# Claude Code polls that endpoint ~every few minutes, so this is warm within
+# moments of proxy start while Claude Code is in use.
+_CACHED_PLAN: dict[str, str | None] = {"plan": None}
+
+_TIER_MAP = (
+    ("max_20x", "max_20x"),
+    ("max_5x", "max_5x"),
+    ("20x", "max_20x"),
+    ("5x", "max_5x"),
+    ("pro", "pro"),
+    ("free", "free"),
+)
+
+
+def _extract_plan_tier(body: object) -> str | None:
+    """Find a rate-limit-tier string anywhere in a JSON body and normalize it.
+
+    Looks for keys containing 'rate_limit_tier'/'ratelimittier' (any case,
+    any nesting) — e.g. organizationRateLimitTier: 'default_claude_max_5x'.
+    Returns one of max_20x/max_5x/pro/free, or None."""
+    if isinstance(body, dict):
+        for key, value in body.items():
+            normalized_key = key.replace("_", "").lower()
+            if "ratelimittier" in normalized_key and isinstance(value, str):
+                tier_value = value.lower()
+                for marker, plan in _TIER_MAP:
+                    if marker in tier_value:
+                        return plan
+            found = _extract_plan_tier(value)
+            if found:
+                return found
+    elif isinstance(body, list):
+        for item in body:
+            found = _extract_plan_tier(item)
+            if found:
+                return found
+    return None
+
+
+def _is_headless_sdk_call(body: dict | None) -> bool:
+    """True when the request comes from headless `claude -p` (SDK entrypoint).
+
+    Claude Code embeds a billing pseudo-header in the first system block:
+    `cc_entrypoint=cli` for interactive sessions, `cc_entrypoint=sdk-cli` for
+    `claude -p`. The eval worker / llm-client fires headless calls every few
+    seconds, each with a fresh wire session id — bootstrapping those floods
+    /sessions with one-snapshot rows. Only the known-headless marker is
+    excluded; absent/unknown markers still capture (don't break on new CC
+    versions)."""
+    if not body:
+        return False
+    system = body.get("system")
+    blocks: list = system if isinstance(system, list) else [system]
+    for block in blocks[:2]:  # billing header is in the leading block
+        text = block.get("text") if isinstance(block, dict) else block
+        if isinstance(text, str) and "cc_entrypoint=sdk-cli" in text:
+            return True
+    return False
+
+
+def _bootstrap_session_async(provider: str, wire_id: str) -> None:
+    """Run _ensure_session_for_wire_id in a daemon thread (single-flight per wire id)."""
+    with _PENDING_LOCK:
+        if wire_id in _PENDING_BOOTSTRAPS:
+            return
+        _PENDING_BOOTSTRAPS.add(wire_id)
+
+    def run() -> None:
+        try:
+            _ensure_session_for_wire_id(provider, wire_id)
+        except Exception as exc:  # never let a bootstrap error kill the thread silently
+            logger.warning("background bootstrap failed for %s: %s", wire_id[:16], exc)
+        finally:
+            with _PENDING_LOCK:
+                _PENDING_BOOTSTRAPS.discard(wire_id)
+
+    threading.Thread(target=run, daemon=True, name="rulemetric-bootstrap").start()
+
+
+def _resolve_session_id(
+    provider: str,
+    body: dict | None = None,
+    headers: object | None = None,
+) -> str | None:
+    """Return the RuleMetric DB session id this request should be attributed to.
+
+    Resolution order:
+      1. Wire session id from the request body/headers (race-free, per-request)
+         → look up by filename in $TMPDIR/rulemetric/.
+      2. If the wire id has no registry file AND the provider is on the
+         auto-bootstrap allowlist, create the session row on demand and
+         write the registry file (allowlisted providers only — see
+         `_PROVIDERS_WITH_AUTO_BOOTSTRAP`).
+      3. Filesystem registry's currently-active session for the provider
+         (legacy path; relied on for harnesses that don't expose a wire id).
+
+    Callers MUST drop the snapshot on None.
+    """
+    wire_id = _extract_wire_session_id(provider, body, headers)
+    if wire_id:
+        info = find_session_by_external_id(wire_id)
+        if info and info.get("session_id"):
+            return info["session_id"]
+        # No registry file. Kick off auto-bootstrap in the background
+        # (no-op for non-allowlisted providers) and drop THIS snapshot —
+        # blocking the mitmproxy event loop on a 5s HTTP POST would stall
+        # every proxied request. Claude Code resends full context items on
+        # each turn, so attribution starts one snapshot later.
+        if provider in _PROVIDERS_WITH_AUTO_BOOTSTRAP:
+            if _is_headless_sdk_call(body):
+                logger.debug(
+                    "Headless sdk-cli call (wire id %s) — not bootstrapping a session",
+                    wire_id[:8],
+                )
+                return None
+            _bootstrap_session_async(provider, wire_id)
+            return None
+        # Wire id present, no registry file, no auto-bootstrap → drop rather
+        # than fall back. With concurrent same-tool sessions running, the
+        # linker fallback would attribute to whoever else is active.
+        logger.warning(
+            "Wire session id %s (provider %s) has no registry file — "
+            "dropping snapshot rather than risk cross-attribution",
+            wire_id[:8], provider,
+        )
+        return None
+
+    active = find_active_session(provider)
+    if active and active.get("session_id"):
+        return active["session_id"]
+    return None
+
+# Header names safe to capture (never capture auth keys)
+SAFE_REQUEST_HEADERS = (
+    # Anthropic
+    "anthropic-version",
+    "anthropic-beta",
+    # OpenAI / Stainless SDK
+    "openai-organization",
+    "x-request-id",
+    "x-stainless-arch",
+    "x-stainless-os",
+    "x-stainless-runtime",
+    "x-stainless-runtime-version",
+    "x-stainless-lang",
+    "x-stainless-package-version",
+    # Snowflake Cortex
+    "x-snowflake-authorization-token-type",
+    # GitHub Copilot
+    "editor-version",
+    "editor-plugin-version",
+    "x-github-api-version",
+    "copilot-integration-id",
+    # Groq
+    "x-groq-api-version",
+    # Generic
+    "x-api-version",
+    "x-model-id",
+)
+
+SAFE_RESPONSE_HEADERS = (
+    "request-id",
+    "x-request-id",
+    # Anthropic rate limits
+    "anthropic-ratelimit-requests-limit",
+    "anthropic-ratelimit-requests-remaining",
+    "anthropic-ratelimit-tokens-limit",
+    "anthropic-ratelimit-tokens-remaining",
+    # OpenAI-style rate limits (used by Groq, Together, Fireworks, etc.)
+    "x-ratelimit-limit-requests",
+    "x-ratelimit-remaining-requests",
+    "x-ratelimit-limit-tokens",
+    "x-ratelimit-remaining-tokens",
+    "x-ratelimit-reset-requests",
+    "x-ratelimit-reset-tokens",
+    # Timing
+    "server-timing",
+    "x-response-time",
+    # Infrastructure
+    "cf-ray",
+    # Groq
+    "x-groq-id",
+    # OpenRouter
+    "x-openrouter-id",
+)
+
+
+def _parse_response_usage(body: dict) -> dict | None:
+    """Extract usage stats from a response body.
+
+    Normalises both Anthropic naming (``input_tokens``) and OpenAI naming
+    (``prompt_tokens``).  Also extracts ``prompt_tokens_details.cached_tokens``
+    which some OpenAI-compatible providers return.
+    """
+    usage = body.get("usage")
+    if not usage or not isinstance(usage, dict):
+        return None
+    result = {
+        "input_tokens": usage.get("input_tokens") or usage.get("prompt_tokens"),
+        "output_tokens": usage.get("output_tokens") or usage.get("completion_tokens"),
+        "cache_creation_input_tokens": usage.get("cache_creation_input_tokens"),
+        "cache_read_input_tokens": usage.get("cache_read_input_tokens"),
+        "total_tokens": usage.get("total_tokens"),
+    }
+    # Granular cache TTL breakdown (Anthropic ephemeral 5m vs 1h pricing tiers).
+    # Prefer the nested `cache_creation` object when present; fall back to treating
+    # the flat sum as 5m (older response shape). Absent for non-Anthropic providers.
+    cache_creation_obj = usage.get("cache_creation")
+    if isinstance(cache_creation_obj, dict):
+        result["cache_creation_5m"] = cache_creation_obj.get("ephemeral_5m_input_tokens", 0) or 0
+        result["cache_creation_1h"] = cache_creation_obj.get("ephemeral_1h_input_tokens", 0) or 0
+    elif usage.get("cache_creation_input_tokens") is not None:
+        result["cache_creation_5m"] = usage.get("cache_creation_input_tokens") or 0
+        result["cache_creation_1h"] = 0
+    # OpenAI-style prompt_tokens_details (cached_tokens)
+    details = usage.get("prompt_tokens_details")
+    if isinstance(details, dict) and details.get("cached_tokens"):
+        result["cache_read_input_tokens"] = (
+            result.get("cache_read_input_tokens") or details["cached_tokens"]
+        )
+    return result
+
+
+def _parse_response_content(body: dict, provider: str) -> dict:
+    """Extract key fields from a response body."""
+    result: dict = {}
+
+    # Stop reason — Anthropic and Gemini have unique formats; everything else is OpenAI-compatible
+    if provider == "anthropic":
+        result["stop_reason"] = body.get("stop_reason")
+    elif provider == "gemini":
+        candidates = body.get("candidates", [])
+        if candidates:
+            result["stop_reason"] = candidates[0].get("finishReason")
+    else:
+        # OpenAI-compatible format (covers openai, groq, together, fireworks, deepseek, etc.)
+        choices = body.get("choices", [])
+        if choices:
+            result["stop_reason"] = choices[0].get("finish_reason")
+
+    # Model actually used (may differ from requested)
+    result["model_used"] = body.get("model") or body.get("modelId")
+
+    # Anthropic request ID
+    result["request_id"] = body.get("id")
+
+    # Response content blocks (for seeing tool_use calls, thinking blocks, etc.)
+    if provider == "anthropic":
+        content = body.get("content") or []
+        # Summarize content blocks by type
+        block_types = {}
+        for block in content:
+            btype = block.get("type", "unknown")
+            block_types[btype] = block_types.get(btype, 0) + 1
+        result["content_block_types"] = block_types
+
+        # Extract thinking blocks
+        thinking_blocks = [b for b in content if b.get("type") == "thinking"]
+        if thinking_blocks:
+            result["thinking_token_count"] = sum(
+                len(b.get("thinking", "")) // 4 for b in thinking_blocks
+            )
+
+        # Extract text content for the timeline
+        text_blocks = [b.get("text", "") for b in content if b.get("type") == "text"]
+        if text_blocks:
+            result["text_content"] = "\n".join(text_blocks)
+
+    elif provider in ("openai", "github_copilot_chat"):
+        choices = body.get("choices") or []
+        if choices and isinstance(choices[0], dict):
+            message = choices[0].get("message") or {}
+            text = message.get("content") if isinstance(message, dict) else None
+            if text:
+                result["text_content"] = text
+
+    return result
+
+
+def _promote_actual_model(snapshot: dict) -> None:
+    """Prefer the response-reported model as the snapshot's primary model.
+
+    Keep the originally requested model in api_metadata when it differs so
+    the UI and downstream consumers can show the actual model while still
+    preserving what the client asked for.
+    """
+    response = snapshot.get("response")
+    if not isinstance(response, dict):
+        return
+
+    model_used = response.get("model_used")
+    if not isinstance(model_used, str) or not model_used:
+        return
+
+    requested_model = snapshot.get("model")
+    if isinstance(requested_model, str) and requested_model and requested_model != model_used:
+        api_metadata = snapshot.get("api_metadata")
+        if isinstance(api_metadata, dict):
+            api_metadata.setdefault("requested_model", requested_model)
+        else:
+            snapshot["api_metadata"] = {"requested_model": requested_model}
+
+    snapshot["model"] = model_used
+
+
+class RuleMetricAddon:
+    """mitmproxy addon that intercepts LLM API requests and responses."""
+
+    _PENDING_MAX_AGE = 300  # evict pending entries older than 5 minutes
+
+    def __init__(self) -> None:
+        self.project_path = os.environ.get("RULEMETRIC_PROJECT_PATH", "")
+        self._snapshot_count = 0
+        self._error_count = 0
+        # Store pending snapshots keyed by flow id, so response() can enrich them
+        self._pending: dict[str, dict] = {}
+        # Belt-and-suspenders for hot-reload: mitmproxy reloads the addon
+        # script when this file changes, but it does NOT reload subordinate
+        # imports (`reporter`, `providers`, `sse_parser`, etc.) — those stay
+        # cached in sys.modules from the first load. Without this, edits to
+        # `reporter.py` are invisible to the addon, and worse, removed/renamed
+        # symbols cause ImportError on the next addon reload (silent failure
+        # — mitmproxy keeps proxying traffic but the addon is dead). We hit
+        # this on 2026-05-04 when `start_drainer` was added to reporter.py.
+        # Force-reload the modules we depend on so a hot-reload picks up the
+        # latest code from disk, not the cached version.
+        import importlib
+        for mod_name in ('reporter', 'providers', 'sse_parser', 'secret_redactor', 'context_classifier'):
+            mod = sys.modules.get(mod_name)
+            if mod is not None:
+                importlib.reload(mod)
+        # Spool drainer: replays events that exhausted retries during API outages.
+        # Idempotent — safe to call from __init__ even when the addon is
+        # reloaded. Started in __init__ rather than `load()` so it runs in
+        # mitmdump and unit tests alike.
+        from reporter import start_drainer
+        start_drainer()
+        # Drift detection: write our version to a file the gateway watches.
+        # When the CLI is upgraded, the new `proxy start` injects a new
+        # RULEMETRIC_CLI_VERSION; the gateway compares it to its own bundled
+        # version and restarts mitmproxy on drift. Without this, a fresh CLI
+        # install would not restart the long-running proxy that's still
+        # loading old code.
+        cli_version = os.environ.get("RULEMETRIC_CLI_VERSION", "unknown")
+        try:
+            config_dir = os.path.expanduser(
+                os.environ.get("RULEMETRIC_CONFIG_DIR") or "~/.config/rulemetric"
+            )
+            os.makedirs(config_dir, exist_ok=True)
+            version_path = os.path.join(config_dir, "proxy-addon.version")
+            with open(version_path, "w") as f:
+                f.write(cli_version + "\n")
+        except OSError as exc:
+            logger.warning("Failed to write proxy-addon.version: %s", exc)
+        logger.info(
+            "RuleMetric addon initialized (project: %s, version: %s)",
+            self.project_path,
+            cli_version,
+        )
+
+    # ─── Memory guard: stream bodies the addon will never parse ──────────
+    #
+    # mitmproxy buffers full request/response bodies in memory unless
+    # `.stream = True` is set at headers time. Through this proxy flows ALL
+    # of the user's dev traffic (VS Code CDN downloads, Datadog intake,
+    # telemetry, extension updates) — buffering it ballooned mitmdump to
+    # ~1 GB within a minute and macOS jetsam SIGKILLed it every ~2 min
+    # (last exit reason OS_REASON_JETSAM, 200+ restarts/day), which is why
+    # the /usage dashboard went stale: the proxy was dead more often than
+    # alive and the gateway routed direct. Only flows we actually parse
+    # (detected LLM providers + the oauth/usage poll) may be buffered.
+
+    def _is_oauth_usage_flow(self, flow: http.HTTPFlow) -> bool:
+        return (
+            flow.request.method == "GET"
+            and flow.request.pretty_host == self._OAUTH_USAGE_HOST
+            and flow.request.path.split("?", 1)[0] == self._OAUTH_USAGE_PATH
+        )
+
+    def _flow_is_parsed(self, flow: http.HTTPFlow) -> bool:
+        """True when request/response bodies are needed by this addon."""
+        if detect_provider(flow.request.pretty_host, flow.request.path) is not None:
+            return True
+        return self._is_oauth_usage_flow(flow)
+
+    def requestheaders(self, flow: http.HTTPFlow) -> None:
+        if not self._flow_is_parsed(flow):
+            flow.request.stream = True
+
+    def responseheaders(self, flow: http.HTTPFlow) -> None:
+        if not self._flow_is_parsed(flow):
+            flow.response.stream = True
+
+    def request(self, flow: http.HTTPFlow) -> None:
+        """Called for each HTTP request passing through the proxy."""
+        # Streamed flows have no buffered body to read — and by construction
+        # they're flows we don't parse anyway.
+        if flow.request.stream:
+            return
+        # Skip internal worker calls (insights, evals) — not user sessions
+        if flow.request.headers.get("X-RuleMetric-Internal"):
+            return
+
+        host = flow.request.pretty_host
+        path = flow.request.path
+
+        provider = detect_provider(host, path)
+        if provider is None:
+            return
+
+        if flow.request.method != "POST":
+            return
+
+        body_text = flow.request.get_text()
+        if not body_text:
+            logger.warning("Empty request body for %s %s (provider: %s)", flow.request.method, path, provider)
+            return
+
+        try:
+            body = json.loads(body_text)
+        except (json.JSONDecodeError, ValueError) as exc:
+            logger.warning("Failed to parse %s request body as JSON: %s (body length: %d)", provider, exc, len(body_text))
+            return
+
+        parser = _get_parser(provider)
+
+        try:
+            snapshot = parser(body)
+        except Exception as exc:
+            logger.error("Parser crashed for provider %s: %s", provider, exc, exc_info=True)
+            self._error_count += 1
+            return
+
+        if snapshot is None:
+            logger.warning("Parser returned None for %s request (model: %s)", provider, body.get("model", "unknown"))
+            return
+
+        snapshot["provider"] = provider
+        snapshot["captured_at"] = datetime.now(timezone.utc).isoformat()
+        snapshot["project_path"] = self.project_path
+
+        # Capture safe request headers
+        headers_to_capture = {}
+        for header_name in SAFE_REQUEST_HEADERS:
+            val = flow.request.headers.get(header_name)
+            if val:
+                headers_to_capture[header_name] = val
+        if headers_to_capture:
+            snapshot["request_headers"] = headers_to_capture
+
+        # Parse anthropic-beta into feature list
+        beta_header = flow.request.headers.get("anthropic-beta")
+        if beta_header:
+            snapshot["beta_features"] = [f.strip() for f in beta_header.split(",") if f.strip()]
+
+        # Copilot Chat fires multiple LLM calls per user turn (main chat +
+        # title-gen + intent classification) — record the per-turn
+        # `x-interaction-id` so the UI can group snapshots within a session.
+        # Stored as snapshot metadata, NOT used for session attribution.
+        interaction_id = flow.request.headers.get("x-interaction-id")
+        if interaction_id:
+            snapshot["interaction_id"] = interaction_id
+
+        session_id = _resolve_session_id(provider, body, flow.request.headers)
+        wire_id = None
+        if not session_id:
+            # Auto-bootstrap may be in flight for this wire id (the resolver
+            # kicked it off in a background thread). Don't drop the snapshot:
+            # park it with session_id=None and retry resolution at response
+            # time — the model's multi-second response gives the bootstrap
+            # ample time to write the registry file. Without this, agents
+            # that make a single LLM call (subagents, scheduled wake-ups)
+            # produce sessions with zero snapshots.
+            wire_id = _extract_wire_session_id(provider, body, flow.request.headers)
+            if wire_id and _is_headless_sdk_call(body):
+                # Headless `claude -p` traffic is deliberately not captured
+                # as sessions (see _is_headless_sdk_call) — skip quietly.
+                return
+            if not (wire_id and provider in _PROVIDERS_WITH_AUTO_BOOTSTRAP):
+                logger.warning(
+                    "No active hook session for %s traffic — snapshot dropped "
+                    "(hook file missing or stale; expected at $TMPDIR/rulemetric/)",
+                    provider,
+                )
+                return
+
+        snapshot["session_id"] = session_id
+
+        # Sequence is assigned server-side (atomic, survives proxy restarts)
+        self._snapshot_count += 1
+        logger.info(
+            "Captured %s request #%d: model=%s, messages=%d, tools=%d, session=%s",
+            provider,
+            self._snapshot_count,
+            snapshot.get("model", "unknown"),
+            snapshot.get("message_count", 0),
+            snapshot.get("tool_count", 0),
+            session_id,
+        )
+
+        # Store snapshot pending response enrichment
+        self._pending[flow.id] = {
+            "snapshot": snapshot,
+            "session_id": session_id,
+            "wire_id": wire_id,
+            "provider": provider,
+            "created_at": time.monotonic(),
+        }
+
+        # Evict stale entries to prevent memory leaks from aborted requests
+        self._evict_stale_pending()
+
+    def response(self, flow: http.HTTPFlow) -> None:
+        """Called when the response is received — enrich snapshot with usage/stop_reason."""
+        # Phase 3a: intercept Claude Code's `/api/oauth/usage` polls so the
+        # research pipeline can observe rate-limit utilization without
+        # touching the request flow. This is a side channel — it runs even
+        # when no _pending snapshot exists for this flow.
+        try:
+            self._maybe_report_oauth_usage(flow)
+        except Exception as exc:  # pragma: no cover — defensive
+            logger.debug("oauth_usage observe failed: %s", exc)
+
+        # Phase 3b (Strategy C): parse rate-limit response headers for any
+        # adapter that has registered a `headers` handler (e.g. Codex).
+        # No-ops when no adapter matches the host or headers are absent.
+        try:
+            self._maybe_report_live_headers(flow)
+        except Exception as exc:  # pragma: no cover — defensive
+            logger.debug("live_headers observe failed: %s", exc)
+
+        pending = self._pending.pop(flow.id, None)
+        if pending is None:
+            return
+
+        snapshot = pending["snapshot"]
+        session_id = pending["session_id"]
+        provider = pending["provider"]
+
+        if not session_id:
+            # The request was parked while auto-bootstrap ran (see request()).
+            # By response time the bootstrap thread has normally written the
+            # registry file — resolve now or drop.
+            wire_id = pending.get("wire_id")
+            info = find_session_by_external_id(wire_id) if wire_id else None
+            session_id = info.get("session_id") if info else None
+            if not session_id:
+                logger.warning(
+                    "Bootstrap for wire id %s not done by response time — snapshot dropped",
+                    (wire_id or "?")[:16],
+                )
+                return
+            snapshot["session_id"] = session_id
+
+        # Parse response body — try SSE streaming first, fall back to JSON
+        resp_text = flow.response.get_text() if flow.response else None
+        content_type = flow.response.headers.get("content-type", "") if flow.response else ""
+
+        if resp_text:
+            # Try SSE streaming parse (Claude Code uses stream: true)
+            streaming_result = parse_streaming_response(resp_text, provider, content_type)
+            if streaming_result:
+                usage = streaming_result.get("usage")
+                if usage:
+                    snapshot["usage"] = usage
+                    logger.info(
+                        "Streaming response usage: input=%s, output=%s, cache_read=%s, cache_write=%s",
+                        usage.get("input_tokens"),
+                        usage.get("output_tokens"),
+                        usage.get("cache_read_input_tokens"),
+                        usage.get("cache_creation_input_tokens"),
+                    )
+
+                resp_info = {
+                    k: v for k, v in streaming_result.items()
+                    if k in ("stop_reason", "model_used", "request_id", "content_block_types", "streaming", "text_content")
+                    and v is not None
+                }
+                if resp_info:
+                    snapshot["response"] = resp_info
+            else:
+                # Fallback: non-streaming JSON response
+                try:
+                    resp_body = json.loads(resp_text)
+
+                    usage = _parse_response_usage(resp_body)
+                    if usage:
+                        snapshot["usage"] = usage
+                        logger.info(
+                            "Response usage: input=%s, output=%s, cache_read=%s, cache_write=%s",
+                            usage.get("input_tokens"),
+                            usage.get("output_tokens"),
+                            usage.get("cache_read_input_tokens"),
+                            usage.get("cache_creation_input_tokens"),
+                        )
+
+                    resp_info = _parse_response_content(resp_body, provider)
+                    if resp_info:
+                        snapshot["response"] = resp_info
+
+                except (json.JSONDecodeError, ValueError):
+                    logger.debug("Could not parse response body as JSON or SSE")
+
+        _promote_actual_model(snapshot)
+
+        # Capture safe response headers
+        if flow.response:
+            resp_headers = {}
+            for header_name in SAFE_RESPONSE_HEADERS:
+                val = flow.response.headers.get(header_name)
+                if val:
+                    resp_headers[header_name] = val
+            if resp_headers:
+                snapshot["response_headers"] = resp_headers
+
+            snapshot["response_status"] = flow.response.status_code
+
+        # Now report the enriched snapshot
+        report_snapshot(session_id, snapshot)
+
+        # Also post an assistant_response event for the timeline
+        event_metadata: dict = {}
+        if snapshot.get("usage"):
+            event_metadata["usage"] = snapshot["usage"]
+        if snapshot.get("response"):
+            resp = snapshot["response"]
+            if resp.get("stop_reason"):
+                event_metadata["stop_reason"] = resp["stop_reason"]
+            if resp.get("content_block_types"):
+                event_metadata["content_block_types"] = resp["content_block_types"]
+            if resp.get("model_used"):
+                event_metadata["model"] = resp["model_used"]
+            if resp.get("request_id"):
+                event_metadata["request_id"] = resp["request_id"]
+            if resp.get("streaming") is not None:
+                event_metadata["streaming"] = resp["streaming"]
+
+        # Extract response latency from server-timing header
+        if flow.response:
+            server_timing = flow.response.headers.get("server-timing", "")
+            if "dur=" in server_timing:
+                try:
+                    dur_str = server_timing.split("dur=")[1].split(",")[0].split(";")[0]
+                    event_metadata["response_time_ms"] = int(float(dur_str))
+                except (ValueError, IndexError):
+                    pass
+
+        if snapshot.get("model"):
+            event_metadata.setdefault("model", snapshot["model"])
+
+        # Extract assistant text content for the timeline
+        assistant_text = None
+        response = snapshot.get("response")
+        if isinstance(response, dict):
+            assistant_text = response.get("text_content") or None
+
+        # Build the event — omit sequence so the API auto-assigns the next
+        # number from the shared counter (avoids collision with hook sequences)
+        assistant_event: dict = {
+            "eventType": "assistant_response",
+            "timestamp": snapshot.get("captured_at", datetime.now(timezone.utc).isoformat()),
+            "metadata": event_metadata,
+        }
+        if assistant_text:
+            assistant_event["content"] = assistant_text
+        # Phase 1E: top-level model + tokenUsage so the API writes them to
+        # session_events.model / session_events.token_usage (dedicated columns
+        # used by the insights cost rollup, instead of relying on the per-event
+        # metadata blob).
+        if snapshot.get("model"):
+            assistant_event["model"] = snapshot["model"]
+        if snapshot.get("usage"):
+            assistant_event["tokenUsage"] = snapshot["usage"]
+
+        report_event(session_id, assistant_event)
+
+
+    # ─── Phase 3a: oauth/usage observer ──────────────────────────────────
+    #
+    # Claude Code calls `GET https://api.anthropic.com/api/oauth/usage`
+    # (internal name `fetchUtilization`) periodically. The response shape is:
+    #
+    #   {"rate_limits": {
+    #       "five_hour":      {"used_percentage": <0-100>, "resets_at": <unix>},
+    #       "seven_day":      {"used_percentage": <0-100>, "resets_at": <unix>},
+    #       "seven_day_opus": {"used_percentage": <0-100>, "resets_at": <unix>}
+    #   }}
+    #
+    # `seven_day` is the combined weekly window (presented as the Sonnet ring
+    # in /usage); `seven_day_opus` is the Opus-only sub-limit. Older Claude
+    # Code builds and Pro-tier accounts may omit `seven_day_opus`.
+    #
+    # We forward each window present in `rate_limits` to the research
+    # `observe` endpoint. Fire-and-forget — never blocks Claude Code's
+    # response — and silently no-ops on any parse failure / missing key.
+
+    _OAUTH_USAGE_HOST = "api.anthropic.com"
+    _OAUTH_USAGE_PATH = "/api/oauth/usage"
+    _OAUTH_USAGE_WINDOWS = (
+        ("five_hour", "five_hour_percent"),
+        ("seven_day", "seven_day_percent"),
+        ("seven_day_opus", "seven_day_opus_percent"),
+    )
+
+    def _maybe_report_oauth_usage(self, flow: http.HTTPFlow) -> None:
+        """If the flow is a `GET /api/oauth/usage` response, post observations."""
+        request = flow.request
+        if request.method != "GET":
+            return
+        if request.pretty_host != self._OAUTH_USAGE_HOST:
+            return
+        # Match exact path (strip query string just in case)
+        path = request.path.split("?", 1)[0]
+
+        # Side channel: oauth/account/settings carries the rate-limit tier
+        # (e.g. default_claude_max_5x) that the usage body does NOT — cache
+        # it so usage observations get a real plan instead of 'unknown'.
+        if path == "/api/oauth/account/settings" and flow.response is not None \
+                and flow.response.status_code == 200:
+            try:
+                tier = _extract_plan_tier(json.loads(flow.response.get_text() or "null"))
+            except (json.JSONDecodeError, ValueError):
+                tier = None
+            if tier and tier != _CACHED_PLAN["plan"]:
+                _CACHED_PLAN["plan"] = tier
+                logger.info("detected plan tier from account/settings: %s", tier)
+            return
+
+        if path != self._OAUTH_USAGE_PATH:
+            return
+
+        response = flow.response
+        if response is None or response.status_code != 200:
+            return
+
+        body_text = response.get_text()
+        if not body_text:
+            return
+
+        try:
+            body = json.loads(body_text)
+        except (json.JSONDecodeError, ValueError):
+            return
+
+        if not isinstance(body, dict):
+            return
+
+        # Two wire shapes: pre-June-2026 wrapped the windows in a
+        # `rate_limits` object; newer builds put `five_hour` / `seven_day` /
+        # `seven_day_opus` (plus extra windows we ignore) at the top level.
+        rate_limits = body.get("rate_limits")
+        if not isinstance(rate_limits, dict) or not rate_limits:
+            if any(k in body for k, _lt in self._OAUTH_USAGE_WINDOWS):
+                rate_limits = body
+            else:
+                # Loud on purpose: a silent schema change here killed usage
+                # tracking for a week once (2026-06-03 → 06-10).
+                logger.warning(
+                    "oauth/usage response had no known windows — schema "
+                    "drift? keys=%s", sorted(body.keys()),
+                )
+                return
+
+        # Best-effort session attribution — the oauth/usage call doesn't
+        # carry a session id, so fall back to the linker's current Claude
+        # Code session if any. Source evidence still records the raw body
+        # either way.
+        session_id: str | None = None
+        try:
+            active = find_active_session("anthropic")
+            if active and isinstance(active, dict):
+                session_id = active.get("session_id")
+        except Exception:  # pragma: no cover — defensive
+            session_id = None
+
+        observed: list[tuple[str, float]] = []
+        for wire_key, limit_type in self._OAUTH_USAGE_WINDOWS:
+            window = rate_limits.get(wire_key)
+            if not isinstance(window, dict):
+                continue
+            # `used_percentage` pre-June-2026; renamed `utilization` after.
+            pct = window.get("used_percentage")
+            if pct is None:
+                pct = window.get("utilization")
+            resets_at_raw = window.get("resets_at")
+            if pct is None or resets_at_raw is None:
+                continue
+            try:
+                value = float(pct)
+            except (TypeError, ValueError):
+                continue
+            # Unix epoch pre-June-2026; ISO-8601 string after.
+            try:
+                if isinstance(resets_at_raw, str) and not resets_at_raw.isdigit():
+                    resets_at_iso = datetime.fromisoformat(
+                        resets_at_raw.replace("Z", "+00:00")
+                    ).isoformat()
+                else:
+                    resets_at_iso = datetime.fromtimestamp(
+                        int(resets_at_raw), tz=timezone.utc
+                    ).isoformat()
+            except (TypeError, ValueError, OSError, OverflowError):
+                logger.warning(
+                    "oauth/usage %s: unparseable resets_at=%r", wire_key,
+                    resets_at_raw,
+                )
+                continue
+
+            observation = {
+                "provider": "anthropic",
+                "plan": _CACHED_PLAN["plan"] or "unknown",
+                "limitType": limit_type,
+                "value": value,
+                "unit": "percentage",
+                "comparator": "=",
+                "resetsAt": resets_at_iso,
+                "sourceType": "oauth_usage",
+                "sourceUrl": "https://api.anthropic.com/api/oauth/usage",
+                "sourceEvidence": {
+                    "rawResponse": body,
+                    "capturedSessionId": session_id,
+                },
+                "confidence": 1.0,
+            }
+            self._post_observation_async(observation)
+            observed.append((limit_type, value))
+
+        if observed:
+            parts = ", ".join(f"{lt}={v}%" for lt, v in observed)
+            logger.info("observed oauth_usage: %s", parts)
+        else:
+            sample = next(
+                (v for k, v in rate_limits.items() if isinstance(v, dict)), {},
+            )
+            logger.warning(
+                "oauth/usage windows present but none parsed — keys=%s, "
+                "sample window fields=%s",
+                sorted(rate_limits.keys()), sorted(sample.keys()),
+            )
+
+    # ─── Phase 3b: Strategy-C response-header observer ───────────────────
+    #
+    # For providers that surface rate-limit state in response headers
+    # (e.g. Codex: x-ratelimit-remaining-requests, x-ratelimit-reset-requests)
+    # rather than a dedicated poll endpoint, we harvest the headers off every
+    # captured model-call response. Zero extra network traffic — headers are
+    # already in hand.
+    #
+    # The matching logic is intentionally kept in the TypeScript adapter
+    # (`codex.ts liveSource.headers`) so the Python addon stays provider-
+    # agnostic. We call a thin JSON-over-HTTP helper that loads the adapter
+    # registry and runs `matchLiveHeaders`. That helper lives at
+    # GET /api/internal/research/match-headers?host=<host> and returns the
+    # parsed observations (empty array when no adapter matches).
+    #
+    # NOTE: This method is a no-op until the Codex spike (§2.1 of the plan)
+    # fills in the real header names and host in codex.ts. The
+    # matchLiveHeaders() function returns undefined for any host until the
+    # SPIKE_REQUIRED placeholders are replaced.
+
+    def _maybe_report_live_headers(self, flow: http.HTTPFlow) -> None:
+        """Parse rate-limit headers for Strategy-C providers (e.g. Codex).
+
+        Dispatches to a background thread to avoid blocking the mitmproxy
+        event loop — urlopen on the API can take tens of ms.
+        """
+        if flow.response is None:
+            return
+
+        host = flow.request.pretty_host
+        response_headers = dict(flow.response.headers)
+
+        # Quick pre-filter: only proceed if any x-ratelimit-* header is present.
+        if not any(k.lower().startswith("x-ratelimit-") for k in response_headers):
+            return
+
+        # Best-effort session attribution.
+        session_id: str | None = None
+        try:
+            active = find_active_session(host)
+            if active and isinstance(active, dict):
+                session_id = active.get("session_id")
+        except Exception:  # pragma: no cover — defensive
+            pass
+
+        payload = {
+            "host": host,
+            "path": flow.request.path,
+            "responseHeaders": response_headers,
+            "observedAt": datetime.now(timezone.utc).isoformat(),
+            "plan": _CACHED_PLAN.get("plan") or "unknown",
+            "userId": session_id,
+        }
+        threading.Thread(
+            target=self._post_match_headers,
+            args=(payload,),
+            daemon=True,
+            name="rulemetric-live-headers",
+        ).start()
+
+    @staticmethod
+    def _post_match_headers(payload: dict) -> None:
+        """Synchronous POST to match-headers — called from a background thread."""
+        import urllib.error
+        import urllib.request
+        from reporter import _get_api_url, _get_auth_headers
+
+        url = f"{_get_api_url()}/api/internal/research/match-headers"
+        headers = {
+            **_get_auth_headers(),
+            "Content-Type": "application/json",
+            "X-RuleMetric-Internal": "1",
+        }
+        req = urllib.request.Request(
+            url, data=json.dumps(payload).encode(), headers=headers, method="POST"
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=5) as resp:
+                result = json.loads(resp.read())
+            observations = result.get("observations", [])
+            if observations:
+                parts = [f"{o['limitType']}={o['value']}" for o in observations]
+                logger.info("live_headers from %s: %s", payload.get("host"), ", ".join(parts))
+        except (urllib.error.URLError, OSError, json.JSONDecodeError):
+            pass  # fire-and-forget
+
+    def _post_observation_async(self, observation: dict) -> None:
+        """Fire-and-forget POST to the research observe endpoint."""
+        import threading
+        threading.Thread(
+            target=self._post_observation,
+            args=(observation,),
+            daemon=True,
+            name="rulemetric-observe",
+        ).start()
+
+    @staticmethod
+    def _post_observation(observation: dict) -> None:
+        """Synchronous POST — called from a background thread."""
+        import urllib.error
+        import urllib.request
+        from reporter import _get_api_url, _get_auth_headers
+
+        url = f"{_get_api_url()}/api/internal/research/observe"
+        headers = _get_auth_headers()
+        # Mark internal so the addon's own request() handler skips it on the
+        # ingress side (X-RuleMetric-Internal short-circuits the proxy).
+        headers["X-RuleMetric-Internal"] = "1"
+        data = json.dumps(observation).encode("utf-8")
+        req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=5) as resp:
+                if resp.status >= 300:
+                    logger.debug(
+                        "observe POST returned HTTP %d", resp.status,
+                    )
+        except urllib.error.URLError as exc:
+            logger.debug("observe POST failed: %s", exc)
+        except Exception as exc:  # pragma: no cover — defensive
+            logger.debug("observe POST unexpected error: %s", exc)
+
+    # ─── Phase 3c: Strategy-E WebSocket frame observer ───────────────────
+    #
+    # Codex CLI uses a WebSocket connection to chatgpt.com/backend-api/codex/responses.
+    # The server sends a `codex.rate_limits` frame (JSON) carrying primary/secondary
+    # quota usage as percentages. We POST the raw frame text to match-stream-frame
+    # so the TypeScript adapter registry can parse it. Zero extra network traffic
+    # on top of what Codex already receives.
+
+    def websocket_message(self, flow: http.HTTPFlow) -> None:
+        """Called for each WebSocket message frame passing through the proxy."""
+        if not hasattr(flow, 'websocket') or flow.websocket is None:
+            return
+        message = flow.websocket.messages[-1] if flow.websocket.messages else None
+        if message is None or message.from_client:
+            return  # only capture server→client frames (from_client is False for those)
+
+        try:
+            frame_text = message.content.decode("utf-8", errors="replace")
+        except (AttributeError, UnicodeDecodeError):
+            return
+
+        # Quick pre-filter: only forward frames that look like rate_limits events.
+        if "rate_limits" not in frame_text:
+            return
+
+        host = flow.request.pretty_host
+        payload = {
+            "host": host,
+            "path": flow.request.path,
+            "frameText": frame_text,
+            "observedAt": datetime.now(timezone.utc).isoformat(),
+            "plan": _CACHED_PLAN.get("plan") or "unknown",
+        }
+        threading.Thread(
+            target=self._post_match_stream_frame,
+            args=(payload,),
+            daemon=True,
+            name="rulemetric-stream-frame",
+        ).start()
+
+    @staticmethod
+    def _post_match_stream_frame(payload: dict) -> None:
+        """Synchronous POST to match-stream-frame — called from a background thread."""
+        import urllib.error
+        import urllib.request
+        from reporter import _get_api_url, _get_auth_headers
+
+        url = f"{_get_api_url()}/api/internal/research/match-stream-frame"
+        headers = {
+            **_get_auth_headers(),
+            "Content-Type": "application/json",
+            "X-RuleMetric-Internal": "1",
+        }
+        req = urllib.request.Request(
+            url, data=json.dumps(payload).encode(), headers=headers, method="POST"
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=5) as resp:
+                result = json.loads(resp.read())
+            observations = result.get("observations", [])
+            if observations:
+                parts = [f"{o['limitType']}={o['value']}" for o in observations]
+                logger.info("stream_frame from %s: %s", payload.get("host"), ", ".join(parts))
+        except (urllib.error.URLError, OSError, json.JSONDecodeError):
+            pass  # fire-and-forget
+
+    def error(self, flow: http.HTTPFlow) -> None:
+        """Called when a flow errors (timeout, connection refused, etc.) — clean up pending."""
+        pending = self._pending.pop(flow.id, None)
+        if pending:
+            logger.warning(
+                "Flow errored — dropping pending snapshot (provider=%s, session=%s)",
+                pending.get("provider", "unknown"),
+                pending.get("session_id", "NONE"),
+            )
+
+    def _evict_stale_pending(self) -> None:
+        """Remove pending entries older than _PENDING_MAX_AGE seconds."""
+        now = time.monotonic()
+        stale = [fid for fid, p in self._pending.items()
+                 if now - p.get("created_at", now) > self._PENDING_MAX_AGE]
+        for fid in stale:
+            logger.warning("Evicting stale pending entry (flow_id=%s)", fid)
+            self._pending.pop(fid, None)
+
+
+addons = [RuleMetricAddon()]
+
+# Optionally prepend the security scanner addon (runs BEFORE traffic capture).
+# Fails gracefully if llm_guard is not installed or scanner is disabled.
+try:
+    import os as _os
+    if _os.environ.get("RULEMETRIC_SCANNER_MODE", "off") != "off":
+        from security_scanner import SecurityScannerAddon
+        addons.insert(0, SecurityScannerAddon())
+        logger.info("SecurityScannerAddon loaded (mode=%s)", _os.environ.get("RULEMETRIC_SCANNER_MODE"))
+except Exception as _exc:
+    logger.debug("SecurityScannerAddon not loaded: %s", _exc)