Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(mcp): size in tool telemetry, freshness on flows, and an update pointer on stale low answers (#2122)
Raghav Chamadiya31f1d7f059f1
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.mdindex 2b9ae8b4a..da1c4240e 100644--- a/docs/agent/MCP_TOOLS.md+++ b/docs/agent/MCP_TOOLS.md@@ -159,7 +159,7 @@ Resolve refs with `repowise expand <ref>` from a shell, or| `response_budget` | Always: `limit_chars` (the ceiling that applied), `tier` (`default` or `expanded`, chosen by whether the call passed an expansion argument), `serialized_chars` (the size delivered) || `state` | Only when something fired: `degraded` plus `degraded_reasons` mapping each contributing key to its reason (a synthesis reason string, the retrieval legs that broke), `partial`, `truncated`. A coarse roll-up of the response's own flags |-Silence on `stale_warning` means the index is current; don't infer staleness from its absence. `list_repos`, `get_architecture`, `get_blast_radius`, and `get_conformance` don't carry a freshness envelope at all.+Silence on `stale_warning` means the index is current; don't infer staleness from its absence. `list_repos`, `get_architecture`, `get_blast_radius`, and `get_conformance` don't carry a freshness envelope at all. Neither does `search_codebase` when a workspace call merges results from several repos, since there is no single indexed commit to compare.---diff --git a/docs/reference/TELEMETRY.md b/docs/reference/TELEMETRY.mdindex 2c9017034..82c4da65f 100644--- a/docs/reference/TELEMETRY.md+++ b/docs/reference/TELEMETRY.md@@ -65,8 +65,8 @@ generation is used. Never exact counts, never repo or file names:Emitted by the MCP server (`repowise mcp` / `repowise serve`) so we can seewhich tools coding agents actually use and how often answers come back stale or-degraded. Only the tool name and coarse enums/booleans — **never the question,-query, results, paths, or repo/symbol names**:+degraded. Only the tool name, coarse enums/booleans, and the size of the+response, **never the question, query, results, paths, or repo/symbol names**:| Field | Example | Purpose ||---|---|---|@@ -78,6 +78,11 @@ query, results, paths, or repo/symbol names**:| `properties.results_bucket` | `1-3`, `4-10` | Result count for searches (a range) || `properties.index_behind` | `true` / `false` | How often served content is stale || `properties.embedder_degraded` | `true` / `false` | How often search runs on mock vectors |+| `properties.grounding` | `symbol_body` / `extracted` | What a confident answer rests on |+| `properties.degraded` | `no-llm-provider` / `synthesis-failed` | Why an answer carries no synthesised prose |+| `properties.semantic_search` | `true` / `false` | Whether retrieval had a vector leg |+| `properties.response_chars` | `10979` | Serialised size of the response, a count only |+| `properties.response_tokens` | `2744` | The same size as the budget's token estimate |Example `command_run` payload:diff --git a/packages/server/src/repowise/server/mcp_server/_meta.py b/packages/server/src/repowise/server/mcp_server/_meta.pyindex 31e8ffab6..bc272d6b6 100644--- a/packages/server/src/repowise/server/mcp_server/_meta.py+++ b/packages/server/src/repowise/server/mcp_server/_meta.py@@ -520,6 +520,13 @@ EXHAUSTIVE_SWEEP_HINT = ("Grep the name; that is the one job this surface does not do.")+# Appended to a get_answer hint when the answer graded low and the index is+# behind live HEAD; the one place holding both signals says what to do.+INDEX_BEHIND_LOW_CONFIDENCE_HINT = (+ "The index is behind HEAD, so run `repowise update` and ask again before "+ "trusting a low-confidence answer."+)+def answer_hint(confidence: str,diff --git a/packages/server/src/repowise/server/mcp_server/_savings/wrapper.py b/packages/server/src/repowise/server/mcp_server/_savings/wrapper.pyindex 42ca52279..39470a627 100644--- a/packages/server/src/repowise/server/mcp_server/_savings/wrapper.py+++ b/packages/server/src/repowise/server/mcp_server/_savings/wrapper.py@@ -48,10 +48,36 @@ logger = logging.getLogger(__name__)#: ``degraded`` names WHY a get_answer reply carries no synthesised prose (no#: provider, versus a provider that failed), which is the difference between an#: install working as designed and one that broke.+#:+#: ``response_chars`` / ``response_tokens`` size the delivered payload; plain+#: counts, never content, so a field before/after of payload size exists._META_FLAGS = ("index_behind", "embedder_degraded")_RESULT_ENUMS = ("confidence", "retrieval_quality", "grounding", "degraded")+def _response_size(result: Any) -> tuple[int, int] | None:+ """Serialised size of *result* as ``(chars, tokens)``, or ``None`` if unknown.++ The response budget already stamps the compact serialised size on the way+ in, so read that and serialise only when no stamp is present.+ """+ try:+ from repowise.server.mcp_server._budget.budgeter import CHARS_PER_TOKEN++ stamped = None+ if isinstance(result, dict):+ meta = result.get("_meta")+ budget = meta.get("response_budget") if isinstance(meta, dict) else None+ stamped = budget.get("serialized_chars") if isinstance(budget, dict) else None+ if isinstance(stamped, int) and stamped > 0:+ chars = stamped+ else:+ chars = len(json.dumps(result, separators=(",", ":"), default=str))+ except Exception:+ return None+ return chars, chars // CHARS_PER_TOKEN++def _semantic_search_state() -> bool | None:"""The install's vector-leg state, or ``None`` when it was never evaluated."""from repowise.server.mcp_server._meta import semantic_search_state@@ -79,7 +105,7 @@ def _results_count_bucket(result: Any) -> str | None:def _telemetry_properties(tool: str, result: Any, duration_ms: int) -> dict[str, Any]:"""Build the anonymous ``mcp_tool_call`` properties for *result*.- Only coarse enums / booleans / bucketed counts — no user-identifying data.+ Only coarse enums / booleans / bucketed counts / response size, never user-identifying data."""is_error = isinstance(result, dict) and bool(result.get("error"))props: dict[str, Any] = {@@ -100,6 +126,9 @@ def _telemetry_properties(tool: str, result: Any, duration_ms: int) -> dict[str,bucket = _results_count_bucket(result)if bucket is not None:props["results_bucket"] = bucket+ size = _response_size(result)+ if size is not None:+ props["response_chars"], props["response_tokens"] = size# Read from server state rather than from the response. `embedder_degraded`# is False on a keyless install by design, so it only ever catches# misconfiguration and the larger keyless population - retrieval genuinelydiff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/projection.py b/packages/server/src/repowise/server/mcp_server/tool_answer/projection.pyindex f57a98d45..4f311e527 100644--- a/packages/server/src/repowise/server/mcp_server/tool_answer/projection.py+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/projection.py@@ -330,6 +330,23 @@ def _served_paths(payload: dict[str, Any]) -> list[str]:return list(dict.fromkeys(paths))+def _hint_with_update_pointer(+ hint: Any, confidence: Any, freshness: dict[str, Any]+) -> Any:+ """Add the update pointer to a low-confidence hint served off a behind index."""+ if freshness.get("index_behind") is not True or confidence != "low":+ return hint+ # A stale_warning already names the command, so don't say it twice.+ if freshness.get("stale_warning"):+ return hint+ from repowise.server.mcp_server._meta import INDEX_BEHIND_LOW_CONFIDENCE_HINT++ existing = hint.strip() if isinstance(hint, str) else ""+ if not existing:+ return INDEX_BEHIND_LOW_CONFIDENCE_HINT+ return f"{existing} {INDEX_BEHIND_LOW_CONFIDENCE_HINT}"++async def _refresh_freshness(payload: dict[str, Any], repo: str | None) -> None:"""Scope trust metadata to evidence in the final fresh/cache projection."""if repo == "all":@@ -355,6 +372,18 @@ async def _refresh_freshness(payload: dict[str, Any], repo: str | None) -> None:):meta.pop(key, None)meta.update(freshness)+ # An error reply carries confidence "low" too, and its fault is not the+ # index, so the pointer would only misdirect there.+ try:+ hint = _hint_with_update_pointer(+ meta.get("hint"),+ None if payload.get("error") else payload.get("confidence"),+ freshness,+ )+ except Exception:+ return+ if hint:+ meta["hint"] = hintdef projected_answer(fn: Callable[..., Any]) -> Callable[..., Any]:diff --git a/packages/server/src/repowise/server/mcp_server/tool_flows.py b/packages/server/src/repowise/server/mcp_server/tool_flows.pyindex ddf851f18..ad03df16a 100644--- a/packages/server/src/repowise/server/mcp_server/tool_flows.py+++ b/packages/server/src/repowise/server/mcp_server/tool_flows.py@@ -87,7 +87,11 @@ async def get_execution_flows(return {"entry_point": entry_point,"error": f"Symbol not found: {entry_point!r}",- "_meta": _build_meta(timing_ms=(time.perf_counter() - t0) * 1000),+ "_meta": _build_meta(+ timing_ms=(time.perf_counter() - t0) * 1000,+ repository=repository,+ targets=None,+ ),}entry_nodes = [(node, _ep_score(node))]else:@@ -108,12 +112,20 @@ async def get_execution_flows(return {"total_entry_points": 0,"flows": [],- "_meta": _build_meta(timing_ms=(time.perf_counter() - t0) * 1000),+ # No file content served, so freshness never warns here.+ "_meta": _build_meta(+ timing_ms=(time.perf_counter() - t0) * 1000,+ repository=repository,+ targets=[],+ ),}# BFS trace from each entry pointnode_cache: dict[str, GraphNode] = {}flows: list[dict[str, Any]] = []+ # Files the published traces touch, so freshness warns only when one+ # of them changed after indexing.+ trace_paths: set[str] = set()for ep_node, ep_score in entry_nodes:hop_origins: dict[tuple[str, str], str] = {}@@ -144,6 +156,13 @@ async def get_execution_flows(session, repo_id, trace, node_cache)+ for nid in trace:+ cached = node_cache.get(nid)+ # A file node keeps its path in node_id; _meta reduces symbol ids.+ path = (cached.file_path if cached is not None else None) or nid+ if path:+ trace_paths.add(path)+flow: dict[str, Any] = {"entry_point": ep_node.node_id,"entry_point_name": ep_node.name or ep_node.node_id.split("::")[-1],@@ -173,6 +192,8 @@ async def get_execution_flows("_meta": _build_meta(timing_ms=(time.perf_counter() - t0) * 1000,hint="Use get_context(include=['callers','callees']) on any trace node for detail.",+ repository=repository,+ targets=sorted(trace_paths),),}return resultdiff --git a/packages/server/src/repowise/server/mcp_server/tool_search.py b/packages/server/src/repowise/server/mcp_server/tool_search.pyindex 2f3343cb9..622b89768 100644--- a/packages/server/src/repowise/server/mcp_server/tool_search.py+++ b/packages/server/src/repowise/server/mcp_server/tool_search.py@@ -846,6 +846,8 @@ async def _federated_search(# Derive confidence from RRF position_assign_confidence(output, "rrf_score", "confidence_score")+ # No freshness here: results come from several repos at once, so there is+ # no single indexed commit to compare a live HEAD against.response: dict = {"results": output, "_meta": _build_meta()}# Drawn from every repo's ranked list, not the merged cut: a workspace# search that spends its window on module pages should still be able todiff --git a/tests/unit/server/mcp/test_answer_projection.py b/tests/unit/server/mcp/test_answer_projection.pyindex a310f4d85..7206c641e 100644--- a/tests/unit/server/mcp/test_answer_projection.py+++ b/tests/unit/server/mcp/test_answer_projection.py@@ -428,3 +428,85 @@ async def test_missing_generated_docs_can_fall_back_to_local_symbol_evidence(assert result["answer"]assert result["best_guesses"][0]["file"] == "src/auth/service.py"assert result["next_action_hint"]+++def _behind(**extra) -> dict:+ return {"index_behind": True, "indexed_commit": "abc123abc123", **extra}+++def test_low_confidence_on_a_behind_index_points_at_repowise_update():+ from repowise.server.mcp_server._meta import INDEX_BEHIND_LOW_CONFIDENCE_HINT+ from repowise.server.mcp_server.tool_answer.projection import _hint_with_update_pointer++ existing = "Low confidence. Read the listed fallback_targets to verify before answering."+ hint = _hint_with_update_pointer(existing, "low", _behind())++ assert hint == f"{existing} {INDEX_BEHIND_LOW_CONFIDENCE_HINT}"+ assert hint.startswith(existing)+ assert "repowise update" in hint+ assert INDEX_BEHIND_LOW_CONFIDENCE_HINT.count("repowise update") == 1+++def test_the_pointer_is_the_whole_hint_when_there_was_none():+ from repowise.server.mcp_server._meta import INDEX_BEHIND_LOW_CONFIDENCE_HINT+ from repowise.server.mcp_server.tool_answer.projection import _hint_with_update_pointer++ assert _hint_with_update_pointer(None, "low", _behind()) == INDEX_BEHIND_LOW_CONFIDENCE_HINT+ assert _hint_with_update_pointer("", "low", _behind()) == INDEX_BEHIND_LOW_CONFIDENCE_HINT++[email protected]("confidence", ["high", "medium"])+def test_confident_answers_keep_their_hint_on_a_behind_index(confidence):+ from repowise.server.mcp_server.tool_answer.projection import _hint_with_update_pointer++ assert _hint_with_update_pointer(None, confidence, _behind()) is None+ assert _hint_with_update_pointer("Use the answer.", confidence, _behind()) == "Use the answer."+++def test_a_current_index_never_adds_the_pointer():+ from repowise.server.mcp_server.tool_answer.projection import _hint_with_update_pointer++ for freshness in ({"index_behind": False}, {}, {"indexed_commit": "abc123abc123"}):+ assert _hint_with_update_pointer("Low confidence.", "low", freshness) == "Low confidence."+++def test_a_stale_warning_already_names_the_command_so_the_hint_is_left_alone():+ from repowise.server.mcp_server.tool_answer.projection import _hint_with_update_pointer++ freshness = _behind(stale_warning="Index is behind live HEAD, run `repowise update`.")++ assert _hint_with_update_pointer("Low confidence.", "low", freshness) == "Low confidence."+++async def test_refresh_freshness_appends_the_pointer_to_a_low_confidence_reply(+ setup_mcp, monkeypatch+):+ import repowise.server.mcp_server._meta as meta_mod+ from repowise.server.mcp_server._meta import INDEX_BEHIND_LOW_CONFIDENCE_HINT+ from repowise.server.mcp_server.tool_answer.projection import _refresh_freshness++ monkeypatch.setattr(meta_mod, "freshness_from_repo", lambda _repo, targets=None: _behind())++ low = {"confidence": "low", "citations": ["src/auth/service.py"], "_meta": {"hint": "Verify."}}+ high = {"confidence": "high", "citations": ["src/auth/service.py"], "_meta": {"hint": "Verify."}}+ await _refresh_freshness(low, None)+ await _refresh_freshness(high, None)++ assert low["_meta"]["index_behind"] is True+ assert low["_meta"]["hint"] == f"Verify. {INDEX_BEHIND_LOW_CONFIDENCE_HINT}"+ assert high["_meta"]["hint"] == "Verify."+++async def test_an_error_reply_never_gets_the_update_pointer(setup_mcp, monkeypatch):+ import repowise.server.mcp_server._meta as meta_mod+ from repowise.server.mcp_server.tool_answer.projection import _refresh_freshness++ monkeypatch.setattr(meta_mod, "freshness_from_repo", lambda _repo, targets=None: _behind())++ err = {"error": "question is required", "confidence": "low", "citations": [], "_meta": {}}+ await _refresh_freshness(err, None)++ assert err["_meta"]["index_behind"] is True+ assert "hint" not in err["_meta"]diff --git a/tests/unit/server/mcp/test_meta_freshness.py b/tests/unit/server/mcp/test_meta_freshness.pyindex b3a325abc..a21c059c3 100644--- a/tests/unit/server/mcp/test_meta_freshness.py+++ b/tests/unit/server/mcp/test_meta_freshness.py@@ -240,3 +240,62 @@ def test_no_answer_hint_names_an_external_tool() -> None:assert not [h for h in hints if h and "Grep" in h]assert "Grep" not in NO_HITS_RECOVERY_HINTassert "search_codebase" in NO_HITS_RECOVERY_HINT+++async def _stamp_head_commit(sha: str) -> None:+ """Give the fixture repository an indexed commit so freshness has something+ to report. Without it ``freshness_from_repo`` emits only the age fields, and+ a tool that forgot to pass ``repository`` would look identical to one that+ passed it."""+ from sqlalchemy import update++ import repowise.server.mcp_server as mcp_mod+ from repowise.core.persistence.database import get_session+ from repowise.core.persistence.models import Repository++ async with get_session(mcp_mod._session_factory) as session:+ await session.execute(update(Repository).values(head_commit=sha))+++async def test_structured_search_meta_carries_freshness(setup_mcp):+ """A single-repo symbol search compares against one index, so it must say+ which commit that index was built from."""+ from repowise.server.mcp_server import search_codebase++ await _stamp_head_commit(_INDEXED)+ result = await search_codebase("AuthService", mode="symbol")+ assert result["_meta"]["indexed_commit"] == _INDEXED[:12]+++async def test_execution_flows_meta_carries_freshness(setup_mcp):+ """get_execution_flows serves traces over files of one repo, so its+ envelope carries that repo's freshness like every other default tool."""+ from repowise.server.mcp_server.tool_flows import get_execution_flows++ await _stamp_head_commit(_INDEXED)+ result = await get_execution_flows()+ assert result["_meta"]["indexed_commit"] == _INDEXED[:12]+++async def test_execution_flows_targets_name_the_traced_files(setup_mcp, monkeypatch):+ """A stale warning is scoped to what the response served, so the files the+ published traces walk have to reach freshness as targets."""+ from repowise.server.mcp_server import tool_flows++ seen: list = []+ real = tool_flows._build_meta++ def spy(**kwargs):+ seen.append(kwargs)+ return real(**kwargs)++ monkeypatch.setattr(tool_flows, "_build_meta", spy)+ await _stamp_head_commit(_INDEXED)+ result = await tool_flows.get_execution_flows(entry_point="src/auth/service.py")+ assert result["flows"]+ assert result["_meta"]["indexed_commit"] == _INDEXED[:12]+ assert seen[-1]["repository"] is not None+ assert "src/auth/service.py" in seen[-1]["targets"]diff --git a/tests/unit/server/mcp/test_tool_telemetry.py b/tests/unit/server/mcp/test_tool_telemetry.pyindex 38921ba8c..0626e8e0f 100644--- a/tests/unit/server/mcp/test_tool_telemetry.py+++ b/tests/unit/server/mcp/test_tool_telemetry.py@@ -7,11 +7,19 @@ emit is best-effort so it can never break or slow a tool response.from __future__ import annotations+import json+import pytestfrom repowise.server.mcp_server._savings import wrapper+def _size(result) -> tuple[int, int]:+ """The size the wrapper should report, from the same formula the budget uses."""+ chars = len(json.dumps(result, separators=(",", ":"), default=str))+ return chars, chars // 4++class TestTelemetryProperties:@pytest.fixture(autouse=True)def _no_ambient_embedder(self, monkeypatch: pytest.MonkeyPatch):@@ -32,6 +40,7 @@ class TestTelemetryProperties:"_meta": {"index_behind": True, "embedder_degraded": False, "timing_ms": 12.3},}props = wrapper._telemetry_properties("get_answer", result, 42)+ chars, tokens = _size(result)assert props == {"tool": "get_answer","status": "ok",@@ -41,6 +50,8 @@ class TestTelemetryProperties:"grounding": "exact_symbol","index_behind": True,"embedder_degraded": False,+ "response_chars": chars,+ "response_tokens": tokens,}def test_degraded_answer_reports_why_synthesis_was_missing(self):@@ -95,12 +106,45 @@ class TestTelemetryProperties:props = wrapper._telemetry_properties("search_codebase", result, 5)assert props["results_bucket"] == "1-3"# Only coarse keys — no results/paths reach the wire.- assert set(props) == {"tool", "status", "duration_ms", "results_bucket"}+ assert set(props) == {+ "tool",+ "status",+ "duration_ms",+ "results_bucket",+ "response_chars",+ "response_tokens",+ }+ assert (props["response_chars"], props["response_tokens"]) == _size(result)def test_non_dict_result_is_safe(self):props = wrapper._telemetry_properties("get_overview", "unexpected", 1)assert props == {"tool": "get_overview", "status": "ok", "duration_ms": 1}+ def test_response_size_is_the_serialised_payload(self):+ """Size is a number about the payload, not any of its content."""+ result = {"answer": "x" * 100, "confidence": "high"}+ props = wrapper._telemetry_properties("get_answer", result, 1)+ chars, tokens = _size(result)+ assert props["response_chars"] == chars+ assert props["response_tokens"] == tokens == chars // 4++ def test_unserialisable_result_reports_no_size(self, monkeypatch: pytest.MonkeyPatch):+ """A dump that blows up drops the size keys instead of failing the emit."""++ class _Boom:+ @staticmethod+ def dumps(*a, **k):+ raise TypeError("nope")++ monkeypatch.setattr(wrapper, "json", _Boom)+ props = wrapper._telemetry_properties("get_answer", {"confidence": "high"}, 1)+ assert props == {+ "tool": "get_answer",+ "status": "ok",+ "duration_ms": 1,+ "confidence": "high",+ }+@pytest.mark.asyncioasync def test_instrument_emits_one_event(monkeypatch: pytest.MonkeyPatch):@@ -137,3 +181,12 @@ async def test_telemetry_failure_never_breaks_the_tool(monkeypatch: pytest.Monke# The tool result must survive a telemetry emit that raises.out = await wrapper.instrument(get_overview)()assert out == {"ok": True, "_meta": {}}+++def test_response_size_prefers_the_budget_stamp(monkeypatch: pytest.MonkeyPatch):+ """The budget pass already measured the payload; a second dump is waste."""+ monkeypatch.setattr(wrapper, "_semantic_search_state", lambda: None)+ result = {"answer": "x" * 50, "_meta": {"response_budget": {"serialized_chars": 4000}}}+ props = wrapper._telemetry_properties("get_answer", result, 1)+ assert props["response_chars"] == 4000+ assert props["response_tokens"] == 1000