Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

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.md
index 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.md
index 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 see
which 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.py
index 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.py
index 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 genuinely
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/projection.py b/packages/server/src/repowise/server/mcp_server/tool_answer/projection.py
index 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"] = hint
def 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.py
index 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 point
node_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 result
diff --git a/packages/server/src/repowise/server/mcp_server/tool_search.py b/packages/server/src/repowise/server/mcp_server/tool_search.py
index 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 to
diff --git a/tests/unit/server/mcp/test_answer_projection.py b/tests/unit/server/mcp/test_answer_projection.py
index 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.py
index 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_HINT
assert "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.py
index 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 pytest
from 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.asyncio
async 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