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
perf(mcp): lean answer and overview responses (#1922)
Raghav Chamadiya804b753a08a6
diff --git a/packages/core/src/repowise/core/registry/__init__.py b/packages/core/src/repowise/core/registry/__init__.pyindex 5d77f4b48..27fd54965 100644--- a/packages/core/src/repowise/core/registry/__init__.py+++ b/packages/core/src/repowise/core/registry/__init__.py@@ -25,7 +25,13 @@ from .cli_registry import (register_command,register_lazy_command,)-from .mcp_tool_registry import TOOL_TIERS, MCPToolRegistry, ToolEntry, mcp_tool_registry+from .mcp_tool_registry import (+ TOOL_TIERS,+ MCPToolRegistry,+ ToolEntry,+ ToolRecipe,+ mcp_tool_registry,+)from .pipeline_hooks import (HookPhase,HookProgressCallback,@@ -43,6 +49,7 @@ __all__ = ["MCPToolRegistry","PipelineHookRegistry","ToolEntry",+ "ToolRecipe","cli_registry","mcp_tool_registry","pipeline_hooks",diff --git a/packages/core/src/repowise/core/registry/mcp_tool_registry.py b/packages/core/src/repowise/core/registry/mcp_tool_registry.pyindex 9690b16e8..e79a8af57 100644--- a/packages/core/src/repowise/core/registry/mcp_tool_registry.py+++ b/packages/core/src/repowise/core/registry/mcp_tool_registry.py@@ -38,6 +38,15 @@ from typing import AnyTOOL_TIERS = frozenset({"canonical", "utility", "specialist"})+@dataclass(frozen=True)+class ToolRecipe:+ """Compact agent workflow contributed by a tool to the live registry."""++ name: str+ call: str+ requires: tuple[str, ...]++@dataclass(frozen=True)class ToolEntry:"""A registered tool plus the metadata that drives surface selection.@@ -56,6 +65,7 @@ class ToolEntry:tier: str = "canonical"surface_order: int = 1000trust_kind: str | None = None+ recipes: tuple[ToolRecipe, ...] = ()class MCPToolRegistry:@@ -73,6 +83,7 @@ class MCPToolRegistry:tier: str | None = None,surface_order: int = 1000,trust_kind: str | None = None,+ recipes: tuple[ToolRecipe, ...] = (),**kwargs: Any,) -> Callable[[Callable[..., Any]], Callable[..., Any]] | Callable[..., Any]:"""Decorator that schedules a function for FastMCP registration.@@ -111,6 +122,7 @@ class MCPToolRegistry:tier=resolved_tier,surface_order=surface_order,trust_kind=trust_kind,+ recipes=recipes,))fn.__dict__["__repowise_trust_kind__"] = trust_kind@@ -172,4 +184,4 @@ mcp_tool_registry = MCPToolRegistry()"""Process-wide default registry used by the OSS MCP server."""-__all__ = ["TOOL_TIERS", "MCPToolRegistry", "ToolEntry", "mcp_tool_registry"]+__all__ = ["TOOL_TIERS", "MCPToolRegistry", "ToolEntry", "ToolRecipe", "mcp_tool_registry"]diff --git a/packages/server/src/repowise/server/mcp_server/_budget/budgeter.py b/packages/server/src/repowise/server/mcp_server/_budget/budgeter.pyindex 7d6c18f8e..10bfa502a 100644--- a/packages/server/src/repowise/server/mcp_server/_budget/budgeter.py+++ b/packages/server/src/repowise/server/mcp_server/_budget/budgeter.py@@ -195,14 +195,18 @@ def _shed_tail(if dropped:collector.add(label, list(reversed(dropped)))if record_counts:+ prior_reason = container.get(f"{leaf}_reduced_reason")collection_total = max(total, int(container.get(f"{leaf}_total") or 0))container[f"{leaf}_total"] = collection_totalcontainer[f"{leaf}_emitted"] = len(rows)- container[f"{leaf}_reduced_reason"] = "response_budget"+ container[f"{leaf}_reduced_reason"] = _with_budget_reason(prior_reason)container[f"{leaf}_truncated"] = True- container[f"{leaf}_omitted"] = collection_total - len(rows)+ # The omission reference persists only rows dropped by this pass.+ # Earlier projection reductions remain visible in total/emitted and+ # their combined reason, but are not falsely advertised as stored.+ container[f"{leaf}_omitted"] = len(dropped)response["truncated"] = True@@ -217,12 +221,13 @@ def _record_reduction() -> None:"""Keep honest counts for a collection removed as one budget block."""if isinstance(value, list):+ prior_reason = container.get(f"{field}_reduced_reason")total = max(len(value), int(container.get(f"{field}_total") or 0))container[f"{field}_total"] = totalcontainer[f"{field}_emitted"] = emitted- container[f"{field}_reduced_reason"] = "response_budget"+ container[f"{field}_reduced_reason"] = _with_budget_reason(prior_reason)container[f"{field}_truncated"] = True- container[f"{field}_omitted"] = total - emitted+ container[f"{field}_omitted"] = len(value)returnif not isinstance(value, dict):return@@ -246,6 +251,16 @@ def _record_reduction(visit(value, path)+def _with_budget_reason(prior_reason: Any) -> str:+ """Append final-delivery budgeting to reduction provenance at most once."""+ if not prior_reason:+ return "response_budget"+ reason = str(prior_reason)+ if reason == "response_budget" or reason.endswith("_and_response_budget"):+ return reason+ return f"{reason}_and_response_budget"++# Heavy optional fields we can strip from a target's docs block without losing# its identity. Ordering matters: earlier entries are dropped first because they# carry the most bytes per unit of navigational value.diff --git a/packages/server/src/repowise/server/mcp_server/_budget/contracts.py b/packages/server/src/repowise/server/mcp_server/_budget/contracts.pyindex 1406013eb..bb6a2b4d1 100644--- a/packages/server/src/repowise/server/mcp_server/_budget/contracts.py+++ b/packages/server/src/repowise/server/mcp_server/_budget/contracts.py@@ -82,18 +82,16 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {"fallback_targets[]","fallback_targets",),- expansion_argument=None,+ expansion_argument="include",protected=("answer", "confidence", "citations", "next_action_hint"),),"get_overview": ResponseBudgetContract("blocks",("cross_repo_topology",- "tool_guide",- "tool_surface.canonical",- "tool_surface.default",- "tool_surface.utilities","tool_surface.opt_in",+ "tool_surface.tools[]",+ "tool_surface.recipes[]","guided_tour_hint","guided_tour","reading_order_hint",diff --git a/packages/server/src/repowise/server/mcp_server/_tool_selection.py b/packages/server/src/repowise/server/mcp_server/_tool_selection.pyindex ee568b5a2..39b783a75 100644--- a/packages/server/src/repowise/server/mcp_server/_tool_selection.py+++ b/packages/server/src/repowise/server/mcp_server/_tool_selection.py@@ -23,6 +23,7 @@ untouched.from __future__ import annotations+import inspectimport loggingfrom collections.abc import Iterable, Sequencefrom pathlib import Path@@ -257,10 +258,12 @@ def selected_tool_names(*, is_workspace: bool) -> set[str]:return resolve_enabled_tools(mcp_tool_registry.entries(), is_workspace=is_workspace)-def _tool_description(name: str) -> str:+def _tool_description(name: str, fn: Any | None = None) -> str:"""One-line description for a tool, from its registered FastMCP schema."""tool = (_full_surface or {}).get(name)desc = getattr(tool, "description", "") or ""+ if not desc and fn is not None:+ desc = inspect.getdoc(fn) or ""return desc.strip().split("\n", 1)[0].strip()@@ -273,13 +276,21 @@ def registry_tool_rows(entries: Iterable[ToolEntry] | None = None) -> list[dict[return [{"name": entry.name,- "description": _tool_description(entry.name),+ "description": _tool_description(entry.name, entry.fn),"tier": entry.tier,"default_single_repo": entry.name in single_default,"default_workspace": entry.name in workspace_default,"eligible_single_repo": not entry.requires_workspace,"eligible_workspace": True,"requires_workspace": entry.requires_workspace,+ "recipes": [+ {+ "name": recipe.name,+ "call": recipe.call,+ "requires": list(recipe.requires),+ }+ for recipe in entry.recipes+ ],}for entry in sorted(catalog, key=lambda item: (item.surface_order, item.name))]diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py b/packages/server/src/repowise/server/mcp_server/tool_answer/answer.pyindex 1062556d1..a5a092de1 100644--- a/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/answer.py@@ -55,6 +55,7 @@ import timefrom typing import NamedTuplefrom repowise.core.persistence.database import get_session+from repowise.core.registry import ToolRecipefrom repowise.core.registry import mcp_tool_registry as mcpfrom repowise.server.mcp_server._answer_context import (_MAX_CHARS_PER_HIT_EXCERPT,@@ -123,9 +124,9 @@ from repowise.server.mcp_server.tool_answer.confidence import (_retrieval_quality,dominance_reason,)-from repowise.server.mcp_server.tool_answer.config import (+from repowise.server.mcp_server.tool_answer.config import ( # noqa: F401_GATED_EXCERPT_CHARS,- _LEAN_HIGH_DROP_KEYS, # noqa: F401 — re-exported for tests that assert the key set+ _LEAN_HIGH_DROP_KEYS, # re-exported for tests that assert the key set_PAGE_EXCERPT_HITS,_SYSTEM_PROMPT,_USER_TEMPLATE,@@ -149,17 +150,18 @@ from repowise.server.mcp_server.tool_answer.evidence import (_repo_root,)from repowise.server.mcp_server.tool_answer.payload import (- _apply_lean_high,+ _apply_lean_high, # noqa: F401 — backward-compatible helper re-export_build_best_guesses, # noqa: F401 — re-exported: imported from here by tests_drop_duplicated_guess_excerpts, # noqa: F401 — re-exported for the same reason_no_answer_payload,- _trim_served_payload,+ _trim_served_payload, # noqa: F401 — backward-compatible helper re-export_union_answer_payload,_with_candidates,build_abstain_payload,build_synthesized_payload,build_value_payload,)+from repowise.server.mcp_server.tool_answer.projection import projected_answerfrom repowise.server.mcp_server.tool_answer.retrieval import (_apply_domain_penalty,_attach_page_excerpts,@@ -360,11 +362,11 @@ async def _run_retrieval_pipeline(return _Retrieved(hits, resolved_pool, question_ids, homonyms, flow_paths)[email protected](surface_order=10)async def get_answer(question: str,scope: str | None = None,repo: str | None = None,+ include: list[str] | None = None,) -> dict:"""Synthesised answer with citations and a calibrated trust signal.@@ -385,13 +387,15 @@ async def get_answer(that bears on the question — evidence beside the answer, not a correctionof it. Weigh it against the answer; ``still_true`` says how current it is.- Responses fit 24,000 serialized chars. Reduced evidence carries counts and- recovery refs in ``_meta.omitted``; storage failures are explicit.+ Responses fit 24,000 serialized chars. Pass ``include=["evidence"]`` for+ the deduplicated expanded evidence projection (32,000 chars). Reductions+ carry counts and an exact recovery call.Args:question: developer question.scope: optional path-prefix filter (e.g. "src/pkg/").repo: usually omitted.+ include: optional ``["evidence"]`` expanded projection."""if repo == "all":return _unsupported_repo_all("get_answer")@@ -614,7 +618,7 @@ async def get_answer(# evidence, so they name only what differs between them: why, and what to# tell the caller.async def _degrade(reason: str, note: str) -> dict:- return await _degraded_payload(+ payload = await _degraded_payload(reason=reason,note=note,question=question,@@ -628,6 +632,10 @@ async def get_answer(agreement_dominant=agreement_dominant,resolved_pool=resolved_pool,)+ degraded_legs = _degraded_legs(_retrieval_legs())+ if degraded_legs:+ payload.setdefault("_meta", {})["retrieval_degraded"] = degraded_legs+ return _with_candidates(payload, resolved_pool)provider = _resolve_provider_for_answer(getattr(ctx, "path", None))if provider is None:@@ -641,8 +649,7 @@ async def get_answer()return await _degrade("no-llm-provider",- "DEGRADED: no LLM provider configured (set REPOWISE_PROVIDER "- "+ API key). Synthesis is what is missing here, not retrieval.",+ "Synthesis is unavailable; local retrieval and source evidence remain usable.",)# Decision fusion (why-shaped questions only) + structured prelude. Both@@ -778,11 +785,6 @@ async def get_answer(# actually fell over, so a healthy response pays nothing for it.if degraded:payload["_meta"]["retrieval_degraded"] = degraded- _apply_lean_high(payload, question)- # After the cache write above and after lean-high (which can remove- # ``best_guesses`` outright), so the cut sees the finished payload and the- # cached row keeps the shape its schema version promises.- _trim_served_payload(payload)# After the cache write above, deliberately. That write copies the payload# as it stood then, so the episode reaches the caller and never the cache# row, which is why adding it needs no _ANSWER_SCHEMA_VERSION bump: a row@@ -795,3 +797,54 @@ async def get_answer(repo_name=getattr(repository, "name", None),)return payload+++# Keep the orchestrator as a literal ``get_answer`` definition for the source-+# shape invariants that audit its early returns. The exported function below is+# also literal (rather than a decorator-generated coroutine), because CLI tool+# adapters inspect ``cr_code.co_qualname`` to confirm they invoked the requested+# tool. Both paths still share the one projector here.+_get_answer_raw = get_answer+_projected_get_answer = projected_answer(_get_answer_raw)+++ surface_order=10,+ recipes=(+ ToolRecipe(+ "answer_question",+ 'get_answer(question="how does X work?")',+ ("get_answer",),+ ),+ ),+)+async def get_answer(+ question: str,+ scope: str | None = None,+ repo: str | None = None,+ include: list[str] | None = None,+) -> dict:+ """Answer a how, where, or why question in one evidence-grounded call.++ High confidence is content-grounded and may be used directly. Medium+ confidence keeps the smallest verification evidence; low confidence leads+ with an actionable local conclusion and ranked evidence. Provider keys and+ network access are optional: local source, symbols, FTS, rationale, and+ data-shape evidence remain usable when embeddings or synthesis fail.++ Responses fit 24,000 serialized characters. Pass ``include=["evidence"]``+ for the deduplicated expanded projection, capped at 32,000. Reductions carry+ totals, emitted counts, reasons, and an exact one-call recovery.++ Args:+ question: Developer question.+ scope: Optional repository-relative path prefix.+ repo: Usually omitted; a workspace alias when needed.+ include: Optional ``["evidence"]`` expanded projection.+ """+ return await _projected_get_answer(+ question=question,+ scope=scope,+ repo=repo,+ include=include,+ )diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/cache.py b/packages/server/src/repowise/server/mcp_server/tool_answer/cache.pyindex 36c34c386..971606abf 100644--- a/packages/server/src/repowise/server/mcp_server/tool_answer/cache.py+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/cache.py@@ -25,10 +25,6 @@ from repowise.server.mcp_server.tool_answer.config import (_ANSWER_SCHEMA_VERSION,)from repowise.server.mcp_server.tool_answer.episodes import attach_episode as _attach_episode-from repowise.server.mcp_server.tool_answer.payload import (- _apply_lean_high,- _trim_served_payload,-)_log = logging.getLogger("repowise.mcp.answer")@@ -168,8 +164,6 @@ async def _serve_cached_answer(targets=[p for p in cached_paths if isinstance(p, str) and p],extra=({"retrieval_degraded": retrieval_degraded} if retrieval_degraded else None),)- _apply_lean_high(payload, question)- _trim_served_payload(payload)# Serve-time, on this path as well as the fresh one: the episode is read# on every call and never cached into an answer, so a disagreement# cannot be frozen into a row and served after it has been superseded.diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/degraded.py b/packages/server/src/repowise/server/mcp_server/tool_answer/degraded.pyindex b2b2be89e..5502f27c2 100644--- a/packages/server/src/repowise/server/mcp_server/tool_answer/degraded.py+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/degraded.py@@ -28,7 +28,6 @@ from repowise.server.mcp_server.tool_answer.evidence import ()from repowise.server.mcp_server.tool_answer.payload import (_build_best_guesses,- _trim_served_payload,_with_candidates,)from repowise.server.mcp_server.tool_answer.retrieval import (@@ -123,6 +122,11 @@ async def _degraded_payload(code_rationale = _drop_already_surfaced(await _gather_code_rationale(ctx, hits, fallback_targets, question), symbol_bodies)+ citations.extend(+ path+ for row in code_rationale+ if (path := row.get("path")) and path not in citations+ )payload: dict = {"answer": summary,@@ -176,12 +180,7 @@ async def _degraded_payload(),"degraded": reason,}- # The serve-time cuts, which this return had never been routed through. It- # is now the only path carrying `best_guesses` beside a populated- # `retrieval`, so without the drop every excerpt ships twice.- return _trim_served_payload(- _with_candidates(payload, resolved_pool if resolved_pool is not None else hits)- )+ return _with_candidates(payload, resolved_pool if resolved_pool is not None else hits)async def _degraded_next_action(symbol_bodies: list[dict], ctx, repository, exclude_spec) -> str: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.pynew file mode 100644index 000000000..c14c3c769--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/projection.py@@ -0,0 +1,374 @@+"""One external projection for every fresh and cached ``get_answer`` reply."""++from __future__ import annotations++import copy+from collections.abc import Callable+from functools import wraps+from typing import Any++_COLLECTIONS = (+ "citations",+ "retrieval",+ "quotes",+ "symbol_bodies",+ "best_guesses",+ "code_rationale",+ "candidates",+ "fallback_targets",+)+++def _path(row: Any) -> str | None:+ if isinstance(row, str):+ return row+ if not isinstance(row, dict):+ return None+ return row.get("path") or row.get("file") or row.get("target_path")+++def _nav_path(row: Any) -> str | None:+ """Comparable file path for navigation rows and symbol-qualified evidence."""+ path = row["file"] if isinstance(row, dict) and row.get("file") else _path(row)+ return path.split("::", 1)[0] if isinstance(path, str) else None+++def _text(row: Any, *keys: str) -> str:+ if not isinstance(row, dict):+ return ""+ for key in keys:+ value = row.get(key)+ if isinstance(value, str) and value.strip():+ return value.strip()+ return ""+++def _unique(rows: list[Any], identity: Callable[[Any], Any]) -> list[Any]:+ seen: set[Any] = set()+ emitted: list[Any] = []+ for row in rows:+ marker = identity(row)+ if marker in seen:+ continue+ seen.add(marker)+ emitted.append(row)+ return emitted+++def _contained(text: str, slabs: list[str]) -> bool:+ compact = " ".join(text.split())+ return bool(compact) and any(compact in " ".join(slab.split()) for slab in slabs)+++def _deduplicate(payload: dict[str, Any]) -> None:+ """Keep each source fragment once, then keep paths only where they add navigation."""+ bodies = _unique(+ list(payload.get("symbol_bodies") or []),+ lambda row: (_path(row), row.get("name"), tuple(row.get("lines") or ())),+ )+ payload["symbol_bodies"] = bodies+ body_text = [_text(row, "source") for row in bodies]++ quotes = _unique(+ [+ row+ for row in (payload.get("quotes") or [])+ if not _contained(_text(row, "quote"), body_text)+ ],+ lambda row: (_path(row), tuple(row.get("lines") or ()), _text(row, "quote")),+ )+ payload["quotes"] = quotes+ quote_text = [_text(row, "quote") for row in quotes]++ rationale = _unique(+ [+ row+ for row in (payload.get("code_rationale") or [])+ if not _contained(+ _text(row, "rationale", "comment", "quote", "source", "text"),+ [*body_text, *quote_text],+ )+ ],+ lambda row: (+ _path(row),+ tuple(row.get("lines") or ()),+ _text(row, "rationale", "comment", "quote", "source", "text"),+ ),+ )+ payload["code_rationale"] = rationale+ rationale_text = [+ _text(row, "rationale", "comment", "quote", "source", "text") for row in rationale+ ]++ guesses: list[dict[str, Any]] = []+ for original in _unique(+ list(payload.get("best_guesses") or []),+ lambda row: (+ _path(row),+ _text(row, "excerpt"),+ _text(row, "why_relevant", "reason"),+ ),+ ):+ row = dict(original) if isinstance(original, dict) else original+ if isinstance(row, dict) and _contained(+ _text(row, "excerpt"), [*body_text, *quote_text, *rationale_text]+ ):+ row.pop("excerpt", None)+ guesses.append(row)+ payload["best_guesses"] = guesses+ guess_text = [_text(row, "excerpt") for row in guesses]++ retrieval: list[dict[str, Any]] = []+ for original in _unique(+ list(payload.get("retrieval") or []),+ lambda row: (+ _path(row),+ row.get("page_id") if isinstance(row, dict) else None,+ _text(row, "excerpt", "snippet"),+ _text(row, "summary"),+ ),+ ):+ row = dict(original) if isinstance(original, dict) else original+ if isinstance(row, dict) and _contained(+ _text(row, "excerpt", "snippet"),+ [*body_text, *quote_text, *rationale_text, *guess_text],+ ):+ row.pop("excerpt", None)+ row.pop("snippet", None)+ retrieval.append(row)+ payload["retrieval"] = retrieval++ citations = _unique(list(payload.get("citations") or []), lambda row: row)+ payload["citations"] = citations+ occupied = {path for path in map(_nav_path, citations) if path}+ occupied.update(+ path+ for rows in (bodies, quotes, rationale, guesses, retrieval)+ for path in map(_nav_path, rows)+ if path+ )++ fallbacks = [+ row+ for row in _unique(list(payload.get("fallback_targets") or []), lambda row: row)+ if _nav_path(row) not in occupied+ ]+ payload["fallback_targets"] = fallbacks++ ranked_paths = {path for path in map(_nav_path, fallbacks) if path}+ candidates = [+ row+ for row in _unique(list(payload.get("candidates") or []), lambda row: _path(row))+ if _nav_path(row) not in occupied and _nav_path(row) not in ranked_paths+ ]+ payload["candidates"] = candidates+++def _rewrite_degraded_answer(payload: dict[str, Any]) -> None:+ """Describe only evidence that survived the external projection."""+ reason = payload.get("degraded")+ if not reason:+ return+ if payload.get("symbol_bodies"):+ payload["answer"] = (+ f"Synthesis is unavailable ({reason}), but symbol_bodies contains live source "+ "for the named code. Use that evidence directly."+ )+ elif payload.get("code_rationale"):+ row = payload["code_rationale"][0]+ conclusion = _text(row, "rationale", "comment", "quote", "source", "text")+ path = _path(row) or "the top source match"+ payload["answer"] = (+ f"Synthesis is unavailable ({reason}). Source rationale in {path}: "+ f"{conclusion[:400]}"+ )+ elif payload.get("best_guesses"):+ first = _path(payload["best_guesses"][0])+ payload["answer"] = (+ f"Synthesis is unavailable ({reason}). Local retrieval points first to "+ f"{first}; best_guesses carries the evidence and ranking reason."+ )+ elif payload.get("retrieval"):+ first = _path(payload["retrieval"][0])+ payload["answer"] = (+ f"Synthesis is unavailable ({reason}). Local retrieval points first to "+ f"{first}; inspect the emitted evidence before answering."+ )+ else:+ payload["answer"] = (+ f"Synthesis is unavailable ({reason}), and no local evidence matched. "+ "Refine the question with a symbol or path."+ )+++def _keep(payload: dict[str, Any], key: str, limit: int | None) -> None:+ rows = payload.get(key)+ if not isinstance(rows, list):+ return+ if limit is None:+ return+ payload[key] = rows[:limit]+++def _default_shape(payload: dict[str, Any], question: str) -> None:+ confidence = payload.get("confidence", "low")+ why = question.lstrip().lower().startswith("why")+ if confidence == "high":+ for key in ("retrieval", "best_guesses", "candidates", "fallback_targets"):+ payload.pop(key, None)+ if not payload.get("grounding"):+ _keep(payload, "symbol_bodies", 1)+ _keep(payload, "quotes", 1)+ if payload.get("quotes") or not why:+ payload.pop("code_rationale", None)+ else:+ _keep(payload, "code_rationale", 1)+ payload.setdefault("next_action_hint", "Use the answer and citations directly.")+ return++ if confidence == "medium":+ _keep(payload, "symbol_bodies", 1)+ _keep(payload, "quotes", 2)+ _keep(payload, "code_rationale", 2)+ if payload.get("best_guesses"):+ payload.pop("retrieval", None)+ _keep(payload, "best_guesses", 2)+ else:+ _keep(payload, "retrieval", 2)+ payload.pop("candidates", None)+ if payload.get("best_guesses") or payload.get("retrieval"):+ payload.pop("fallback_targets", None)+ payload.setdefault(+ "next_action_hint",+ "Verify the top evidence row before relying on details the answer does not settle.",+ )+ return++ _keep(payload, "symbol_bodies", 2)+ _keep(payload, "code_rationale", 2)+ _keep(payload, "quotes", 1)+ if payload.get("best_guesses"):+ payload.pop("retrieval", None)+ _keep(payload, "best_guesses", 3)+ else:+ _keep(payload, "retrieval", 3)+ payload.pop("candidates", None)+ if payload.get("best_guesses") or payload.get("retrieval") or payload.get("symbol_bodies"):+ payload.pop("fallback_targets", None)+ if not str(payload.get("answer") or "").strip():+ payload["answer"] = str(payload.get("note") or "No grounded answer was found.")+ payload.setdefault(+ "next_action_hint",+ "Use the first emitted evidence row; refine the question if it does not resolve the issue.",+ )+++def _record_reductions(+ payload: dict[str, Any], totals: dict[str, int], *, question: str, scope: str | None,+ repo: str | None, expanded: bool+) -> None:+ reduced = False+ for key in _COLLECTIONS:+ total = totals.get(key, 0)+ emitted = len(payload.get(key) or []) if isinstance(payload.get(key), list) else 0+ if total <= emitted:+ continue+ reason = "deduplicated" if expanded else "confidence_projection_and_deduplication"+ payload[f"{key}_total"] = total+ payload[f"{key}_emitted"] = emitted+ payload[f"{key}_reduced_reason"] = reason+ reduced = True+ if reduced and not expanded:+ projection = payload.setdefault("_meta", {}).setdefault("projection", {})+ arguments: dict[str, Any] = {"question": question, "include": ["evidence"]}+ if scope is not None:+ arguments["scope"] = scope+ if repo is not None:+ arguments["repo"] = repo+ projection["recovery"] = {"tool": "get_answer", "arguments": arguments}+++def project_answer_payload(+ raw: dict[str, Any], *, question: str, scope: str | None = None,+ repo: str | None = None, include: list[str] | None = None+) -> dict[str, Any]:+ """Return the cache-independent, confidence-specific external response."""+ payload = copy.deepcopy(raw)+ totals = {+ key: len(payload.get(key) or []) if isinstance(payload.get(key), list) else 0+ for key in _COLLECTIONS+ }+ _deduplicate(payload)+ expanded = "evidence" in set(include or [])+ if not expanded:+ _default_shape(payload, question)+ _rewrite_degraded_answer(payload)+ for key in _COLLECTIONS:+ if not payload.get(key):+ payload.pop(key, None)+ _record_reductions(+ payload, totals, question=question, scope=scope, repo=repo, expanded=expanded+ )+ unknown = sorted(set(include or []) - {"evidence"})+ if unknown:+ payload.setdefault("_meta", {})["ignored_arguments"] = {"include": unknown}+ return payload+++def _served_paths(payload: dict[str, Any]) -> list[str]:+ paths = [path for path in payload.get("citations") or [] if isinstance(path, str)]+ for key in _COLLECTIONS:+ if key == "citations":+ continue+ paths.extend(path for path in map(_path, payload.get(key) or []) if path)+ return list(dict.fromkeys(paths))+++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":+ return+ try:+ from repowise.core.persistence.database import get_session+ from repowise.server.mcp_server._helpers import _get_repo, _resolve_repo_context+ from repowise.server.mcp_server._meta import freshness_from_repo++ ctx = await _resolve_repo_context(repo)+ async with get_session(ctx.session_factory) as session:+ repository = await _get_repo(session)+ freshness = freshness_from_repo(repository, targets=_served_paths(payload))+ except Exception:+ return+ meta = payload.setdefault("_meta", {})+ for key in (+ "index_age_days",+ "indexed_commit",+ "live_head",+ "index_behind",+ "stale_warning",+ ):+ meta.pop(key, None)+ meta.update(freshness)+++def projected_answer(fn: Callable[..., Any]) -> Callable[..., Any]:+ """Project the completed raw result once, regardless of cache or early return."""++ @wraps(fn)+ async def _wrapped(+ question: str,+ scope: str | None = None,+ repo: str | None = None,+ include: list[str] | None = None,+ ) -> dict[str, Any]:+ raw = await fn(question=question, scope=scope, repo=repo, include=include)+ payload = project_answer_payload(+ raw, question=question, scope=scope, repo=repo, include=include+ )+ await _refresh_freshness(payload, repo)+ return payload++ return _wrapped+++__all__ = ["project_answer_payload", "projected_answer"]diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/context.py b/packages/server/src/repowise/server/mcp_server/tool_context/context.pyindex 869de030d..02482c77a 100644--- a/packages/server/src/repowise/server/mcp_server/tool_context/context.py+++ b/packages/server/src/repowise/server/mcp_server/tool_context/context.py@@ -36,6 +36,7 @@ import loggingfrom typing import Anyfrom repowise.core.persistence.database import get_session+from repowise.core.registry import ToolRecipefrom repowise.core.registry import mcp_tool_registry as mcpfrom repowise.server.mcp_server import _statefrom repowise.server.mcp_server._episodes import enrich_episode_counts as _enrich_episodes@@ -76,7 +77,16 @@ _INCLUDE_BLOCKS = frozenset()[email protected](surface_order=20)+ surface_order=20,+ recipes=(+ ToolRecipe(+ "read_file_shape",+ 'get_context(targets=["path"], include=["skeleton"])',+ ("get_context",),+ ),+ ),+)async def get_context(targets: list[str],include: list[str] | None = None,diff --git a/packages/server/src/repowise/server/mcp_server/tool_overview.py b/packages/server/src/repowise/server/mcp_server/tool_overview.pyindex 8b688c0fb..748208286 100644--- a/packages/server/src/repowise/server/mcp_server/tool_overview.py+++ b/packages/server/src/repowise/server/mcp_server/tool_overview.py@@ -72,23 +72,60 @@ _MODULE_CAP = 8_H2_SPLIT_RE = re.compile(r"\n(?=#{1,2}\s)")-def _tool_surface_guide(*, is_workspace: bool) -> dict[str, Any]:- """The advertised surface, projected from the live registry catalog."""- rows = registry_tool_rows()- enabled = selected_tool_names(is_workspace=is_workspace)+def _tool_surface_guide(+ *,+ is_workspace: bool,+ rows: list[dict[str, Any]] | None = None,+ enabled_names: set[str] | None = None,+) -> dict[str, Any]:+ """The selected surface and valid recipes, projected from registry metadata."""+ rows = registry_tool_rows() if rows is None else rows+ enabled = (+ selected_tool_names(is_workspace=is_workspace)+ if enabled_names is None+ else enabled_names+ )default_key = "default_workspace" if is_workspace else "default_single_repo"eligible_key = "eligible_workspace" if is_workspace else "eligible_single_repo"+ selected = [row for row in rows if row["name"] in enabled]+ recipes: list[dict[str, str]] = []+ seen_recipes: set[str] = set()+ for row in selected:+ for recipe in row["recipes"]:+ if recipe["name"] in seen_recipes or not set(recipe["requires"]) <= enabled:+ continue+ seen_recipes.add(recipe["name"])+ recipes.append({"name": recipe["name"], "call": recipe["call"]})+ opt_in = [+ {+ "name": row["name"],+ "description": row["description"],+ "enabled": row["name"] in enabled,+ }+ for row in rows+ if row["tier"] == "specialist" and row[eligible_key]+ ]return {"mode": "workspace" if is_workspace else "single_repo",- "canonical": [row["name"] for row in rows if row["tier"] == "canonical"],- "default": [row["name"] for row in rows if row[default_key]],- "enabled": [row["name"] for row in rows if row["name"] in enabled],- "utilities": [- row["name"] for row in rows if row["tier"] == "utility" and row[eligible_key]- ],- "opt_in": [- row["name"] for row in rows if row["tier"] == "specialist" and row[eligible_key]+ "counts": {+ "enabled": len(selected),+ "default": sum(row[default_key] for row in rows),+ "eligible": sum(row[eligible_key] for row in rows),+ "opt_in_available": len(opt_in),+ "tiers": dict(Counter(row["tier"] for row in selected)),+ },+ "enabled": [row["name"] for row in selected],+ "tools": [+ {+ "name": row["name"],+ "tier": row["tier"],+ "description": row["description"],+ "default": row[default_key],+ }+ for row in selected],+ "opt_in": opt_in,+ "recipes": recipes,}@@ -1062,32 +1099,6 @@ async def get_overview(repo: str | None = None, include: list[str] | None = Noneif ws_footer:result["workspace"] = ws_footer- # Composition recipes live HERE (one overview call per session) so- # the per-tool docstrings — paid on every fresh agent — stay terse.- result["tool_guide"] = {- "first_call": "get_answer for any how/where/why question; trust "- "confidence=high directly (it is content-grounded).",- # NOT "get_context skeleton -> get_symbol for bodies". That routed- # the agent into a per-signature walk, which is where three- # quarters of every measured session's retrieval calls went, on the- # one tool whose payload cannot be trimmed. get_context serves no- # source by default now, so this names the two whole-file routes.- "reading_code": 'get_context(include=["skeleton"]) for a whole file '- "verified, or just Read it. get_symbol only for an id a response "- "already gave you — never file-by-signature.",- "recipes": [- "get_answer low confidence → Read best_guesses[0].file",- "get_context hotspot: true → get_risk before editing",- "get_context decision_records → get_why(targets=[...]) for rationale",- "PR review → get_risk(targets, changed_files) and read directive first",- "search_codebase(query) auto-routes: identifier → symbol hits "- "(pipe symbol_id into get_symbol), path → files (get_context), "- "prose → wiki search. Force with mode=symbol|path|concept|hybrid.",- ],- "reread_triggers": "Only re-read source on bounds: approximate, "- "stale_warning in _meta, or a search hit whose sources are [fts] "- "only (keyword match, no semantic agreement).",- }result["tool_surface"] = _tool_surface_guide(is_workspace=_state._registry is not None)result["_meta"] = _build_meta(repository=repository)diff --git a/packages/server/src/repowise/server/mcp_server/tool_risk/get_risk.py b/packages/server/src/repowise/server/mcp_server/tool_risk/get_risk.pyindex bec021bfc..d90cd7d5c 100644--- a/packages/server/src/repowise/server/mcp_server/tool_risk/get_risk.py+++ b/packages/server/src/repowise/server/mcp_server/tool_risk/get_risk.py@@ -14,6 +14,7 @@ from repowise.core.persistence.models import (GraphEdge,GraphNode,)+from repowise.core.registry import ToolRecipefrom repowise.core.registry import mcp_tool_registry as mcpfrom repowise.server.mcp_server._budget import OmissionCollectorfrom repowise.server.mcp_server._episodes import enrich_episode_counts as _enrich_episodes@@ -78,7 +79,21 @@ def _drop_opt_in_blocks(response: dict, include: set[str]) -> None:holder.pop(key, None)[email protected](surface_order=50)+ surface_order=50,+ recipes=(+ ToolRecipe(+ "assess_hotspot",+ 'get_risk(targets=["path"])',+ ("get_risk",),+ ),+ ToolRecipe(+ "review_change",+ 'get_risk(targets=["path"], changed_files=["path"])',+ ("get_risk",),+ ),+ ),+)async def get_risk(targets: list[str],repo: str | None = None,diff --git a/packages/server/src/repowise/server/mcp_server/tool_search.py b/packages/server/src/repowise/server/mcp_server/tool_search.pyindex 12a056b27..22f25a22d 100644--- a/packages/server/src/repowise/server/mcp_server/tool_search.py+++ b/packages/server/src/repowise/server/mcp_server/tool_search.py@@ -16,6 +16,7 @@ from repowise.core.persistence.models import (Page,)from repowise.core.providers.embedding import store_has_semantic_vectors+from repowise.core.registry import ToolRecipefrom repowise.core.registry import mcp_tool_registry as mcpfrom repowise.core.test_paths import is_test_path, is_test_related_pathfrom repowise.server.mcp_server._answer_pipeline import _RRF_K, _RRF_SCORE_SCALE@@ -995,7 +996,16 @@ async def _structured_search(return _fit_search_response(response, contexts[0].path if contexts else None)[email protected](surface_order=40)+ surface_order=40,+ recipes=(+ ToolRecipe(+ "find_raw_hits",+ 'search_codebase(query="identifier or path", mode="auto")',+ ("search_codebase",),+ ),+ ),+)async def search_codebase(query: str,limit: int = 5,diff --git a/packages/server/src/repowise/server/mcp_server/tool_why.py b/packages/server/src/repowise/server/mcp_server/tool_why.pyindex 91fe85837..5d313686c 100644--- a/packages/server/src/repowise/server/mcp_server/tool_why.py+++ b/packages/server/src/repowise/server/mcp_server/tool_why.py@@ -19,6 +19,7 @@ from repowise.core.persistence.models import ()from repowise.core.precedent.currency import describe_decision_currencyfrom repowise.core.providers.embedding import store_has_semantic_vectors+from repowise.core.registry import ToolRecipefrom repowise.core.registry import mcp_tool_registry as mcpfrom repowise.server.mcp_server._budget import (OmissionCollector,@@ -51,7 +52,16 @@ from repowise.server.mcp_server._why_relevance import ()[email protected](surface_order=70)+ surface_order=70,+ recipes=(+ ToolRecipe(+ "read_rationale",+ 'get_why(targets=["path"])',+ ("get_why",),+ ),+ ),+)async def get_why(query: str | None = None,targets: list[str] | None = None,diff --git a/tests/unit/server/mcp/test_answer_always_synthesize.py b/tests/unit/server/mcp/test_answer_always_synthesize.pyindex 08d42c807..af332af41 100644--- a/tests/unit/server/mcp/test_answer_always_synthesize.py+++ b/tests/unit/server/mcp/test_answer_always_synthesize.py@@ -162,7 +162,8 @@ async def test_flag_off_restores_legacy_abstain(setup_mcp, monkeypatch):monkeypatch.setattr(answer_mod, "_resolve_provider_for_answer", _no_provider)result = await get_answer("how does the alpha module go function work")- assert result["answer"] == "", "flag off abstains — no synthesized prose"+ assert result["answer"], "flag off still leads with an actionable abstention"+ assert "synthesis skipped" in result["answer"]assert result["confidence"] == "low"assert result["best_guesses"], "abstain path still hands back candidates"diff --git a/tests/unit/server/mcp/test_answer_calibration.py b/tests/unit/server/mcp/test_answer_calibration.pyindex 87eb3f0dc..004c2ecbf 100644--- a/tests/unit/server/mcp/test_answer_calibration.py+++ b/tests/unit/server/mcp/test_answer_calibration.py@@ -440,7 +440,7 @@ async def test_value_question_uses_extraction_fast_path(setup_mcp, monkeypatch):assert "MIN_COUNT = 2" in result["answer"]assert "pkg/alpha/one.py:10" in result["answer"]assert result["citations"] == ["pkg/alpha/one.py"]- assert result["retrieval"] == []+ assert "retrieval" not in result@pytest.mark.asyncio@@ -1138,11 +1138,10 @@ async def test_non_dominant_best_guesses_carry_candidate_excerpts(setup_mcp, montop = result["best_guesses"][0]assert top["file"] == "pkg/alpha/one.py"assert top["why_relevant"]- # The content is in the response exactly once: dropped from the guess- # because retrieval carries the identical slab for the same file.- assert "excerpt" not in top- carried = [r.get("excerpt", "") for r in result["retrieval"]]- assert any(e.startswith("Page content for pkg/alpha/one.py") for e in carried)+ # The content is in the response exactly once. The medium projection keeps+ # the actionable best_guess and drops the duplicate retrieval row.+ assert top["excerpt"].startswith("Page content for pkg/alpha/one.py")+ assert "retrieval" not in result# The reply names the ambiguity and points at best_guesses to verify.assert "best_guesses" in result["note"]assert "ambiguous" in result["note"]diff --git a/tests/unit/server/mcp/test_answer_confidence_reasons.py b/tests/unit/server/mcp/test_answer_confidence_reasons.pyindex 330f3f35b..6e4f4ac09 100644--- a/tests/unit/server/mcp/test_answer_confidence_reasons.py+++ b/tests/unit/server/mcp/test_answer_confidence_reasons.py@@ -281,6 +281,4 @@ async def test_a_served_named_body_still_earns_high_on_weak_retrieval(assert "symbol_bodies" in note, "the note must name the evidence it actually used"assert "clearly dominates" not in noteassert "verify against best_guesses" not in note- assert "next_action_hint" not in result, (- "do not send the agent to the candidates the confidence does not rest on"- )+ assert result["next_action_hint"] == "Use the answer and citations directly."diff --git a/tests/unit/server/mcp/test_answer_degraded_evidence.py b/tests/unit/server/mcp/test_answer_degraded_evidence.pyindex 3a97440bc..ad4d211ac 100644--- a/tests/unit/server/mcp/test_answer_degraded_evidence.py+++ b/tests/unit/server/mcp/test_answer_degraded_evidence.py@@ -24,6 +24,7 @@ from repowise.server.mcp_server.tool_answer.answer import (_degraded_payload,_drop_duplicated_guess_excerpts,)+from repowise.server.mcp_server.tool_answer.projection import project_answer_payloaddef _tree(tmp_path, *, body_lines: int = 6) -> SimpleNamespace:@@ -459,8 +460,9 @@ async def test_degraded_does_not_ship_the_excerpt_twice(tmp_path):hits[0]["excerpt"] = "x" * 1500payload = await _degraded(ctx, hits, {"Blueprint"})- assert payload["retrieval"][0]["excerpt"] == "x" * 1500- assert "excerpt" not in payload["best_guesses"][0]+ external = project_answer_payload(payload, question="what is Blueprint")+ assert external["best_guesses"][0]["excerpt"] == "x" * 1500+ assert "retrieval" not in externalasync def test_degraded_keeps_the_guess_excerpt_when_nothing_duplicates_it(tmp_path):diff --git a/tests/unit/server/mcp/test_answer_payload.py b/tests/unit/server/mcp/test_answer_payload.pyindex 9c46e24bb..55ae50577 100644--- a/tests/unit/server/mcp/test_answer_payload.py+++ b/tests/unit/server/mcp/test_answer_payload.py@@ -241,8 +241,11 @@ async def test_high_confidence_drops_retrieval_block(setup_mcp, monkeypatch):result = await get_answer("how does the beta module go function work")assert result["confidence"] == "high"- assert result["retrieval"] == []- assert result["fallback_targets"], "routing targets survive the diet"+ assert "retrieval" not in result+ assert result["citations"], "trust-bearing paths survive the projection"+ assert result["_meta"]["projection"]["recovery"]["arguments"]["include"] == [+ "evidence"+ ]_assert_no_underscore_keys(result)@@ -279,9 +282,8 @@ async def test_non_dominant_synthesizes_with_evidence(setup_mcp, monkeypatch):assert result["confidence"] == "medium"assert result["answer"], "non-dominant retrieval now carries synthesized prose"assert result["best_guesses"]- for entry in result["retrieval"]:- assert "page_id" not in entry- assert entry.get("path")+ assert "retrieval" not in result+ assert all(entry.get("file") for entry in result["best_guesses"])_assert_no_underscore_keys(result)diff --git a/tests/unit/server/mcp/test_answer_projection.py b/tests/unit/server/mcp/test_answer_projection.pynew file mode 100644index 000000000..46de296e2--- /dev/null+++ b/tests/unit/server/mcp/test_answer_projection.py@@ -0,0 +1,421 @@+"""Lean, cache-invariant external projections for ``get_answer``."""++from __future__ import annotations++import copy+import json+from types import SimpleNamespace++import pytest++from repowise.server.mcp_server.tool_answer.projection import project_answer_payload++_HITS = [+ {"page_id": "file_page:src/auth/service.py", "score": 6.0},+ {"page_id": "file_page:src/auth/middleware.py", "score": 1.0},+]+++class _Provider:+ provider_name = "mock"+ model_name = "mock-1"++ def __init__(self, content: str, *, fail: bool = False) -> None:+ self.content = content+ self.fail = fail+ self.calls = 0++ async def generate(self, **kwargs):+ self.calls += 1+ if self.fail:+ raise RuntimeError("offline synthesis")+ return SimpleNamespace(content=self.content)+++def _patch_retrieval(monkeypatch, answer_mod, scores=(6.0, 1.0)):+ async def _fake_retrieve(question, ctx):+ return [dict(hit, score=score) for hit, score in zip(_HITS, scores, strict=True)]++ async def _fake_hydrate(hits, ctx, *, scope=None):+ for hit in hits:+ hit["target_path"] = hit["page_id"].removeprefix("file_page:")+ hit["title"] = hit["target_path"]+ hit["summary"] = "Authentication evidence"+ hit["snippet"] = "AuthService validates a request and middleware calls it."+ hit["excerpt"] = "class AuthService:\n def check(self): ..."+ hit["page_type"] = "file_page"+ return hits++ monkeypatch.setattr(answer_mod, "_hybrid_retrieve", _fake_retrieve)+ monkeypatch.setattr(answer_mod, "_hydrate_hits", _fake_hydrate)+++def _without_meta(payload: dict) -> dict:+ result = copy.deepcopy(payload)+ result.pop("_meta", None)+ return result+++async def test_fresh_and_cached_answers_share_one_external_contract(setup_mcp, monkeypatch):+ import repowise.server.mcp_server._meta as meta_mod+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import get_answer, tool_middleware++ _patch_retrieval(monkeypatch, answer_mod)+ provider = _Provider("Authentication is implemented in src/auth/service.py.")+ monkeypatch.setattr(answer_mod, "_resolve_provider_for_answer", lambda _path: provider)++ def freshness(_repository, targets=None):+ result = {"index_behind": True}+ if "src/auth/middleware.py" in (targets or []):+ result["stale_warning"] = "dropped evidence changed"+ return result++ monkeypatch.setattr(meta_mod, "freshness_from_repo", freshness)+ call = tool_middleware(get_answer)++ fresh = await call("where is authentication implemented")+ cached = await call("where is authentication implemented")++ assert fresh["confidence"] == "high"+ assert cached["_meta"]["cached"] is True+ assert _without_meta(fresh) == _without_meta(cached)+ assert "stale_warning" not in fresh["_meta"]+ assert "stale_warning" not in cached["_meta"]+ assert provider.calls == 1+++async def test_scoped_cache_identity_isolated_and_projected_the_same(setup_mcp, monkeypatch):+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import get_answer, tool_middleware++ _patch_retrieval(monkeypatch, answer_mod)+ provider = _Provider("Authentication is implemented in src/auth/service.py.")+ monkeypatch.setattr(answer_mod, "_resolve_provider_for_answer", lambda _path: provider)+ call = tool_middleware(get_answer)++ unscoped = await call("where is scoped authentication implemented")+ scoped = await call("where is scoped authentication implemented", scope="src/auth")+ scoped_cached = await call("where is scoped authentication implemented", scope="src/auth")++ assert provider.calls == 2+ assert scoped_cached["_meta"]["cached"] is True+ assert _without_meta(scoped) == _without_meta(scoped_cached)+ assert unscoped["_meta"].get("cached") is not True+++def _raw(confidence: str) -> dict:+ return {+ "answer": "Use AuthService.check.",+ "citations": ["src/auth/service.py"],+ "confidence": confidence,+ "retrieval_quality": "high" if confidence == "high" else "partial",+ "fallback_targets": ["src/auth/service.py", "src/auth/middleware.py"],+ "retrieval": [+ {"path": "src/auth/service.py", "excerpt": "def check(): return True"},+ {"path": "src/auth/middleware.py", "excerpt": "check()"},+ ],+ "quotes": [+ {"path": "src/auth/service.py", "lines": [2, 2], "quote": "return True"}+ ],+ "symbol_bodies": [+ {+ "path": "src/auth/service.py",+ "name": "check",+ "lines": [1, 2],+ "source": "def check():\n return True",+ }+ ],+ "best_guesses": [+ {+ "file": "src/auth/service.py",+ "why_relevant": "defines check",+ "excerpt": "def check(): return True",+ }+ ],+ "candidates": [+ {"path": "src/auth/service.py"},+ {"path": "src/auth/middleware.py"},+ {"path": "src/auth/routes.py"},+ ],+ "code_rationale": [+ {"path": "src/auth/service.py", "comment": "return True"}+ ],+ "_meta": {"contract_version": 1},+ }+++def test_high_medium_and_low_are_intentionally_different_shapes():+ high = project_answer_payload(_raw("high"), question="how does auth work")+ medium = project_answer_payload(_raw("medium"), question="how does auth work")+ low = project_answer_payload(_raw("low"), question="how does auth work")++ assert "retrieval" not in high and "best_guesses" not in high+ assert "retrieval" not in medium and len(medium["best_guesses"]) == 1+ assert "best_guesses" in low and "retrieval" not in low+ assert high["next_action_hint"] == "Use the answer and citations directly."+ assert medium["next_action_hint"] != high["next_action_hint"]+ assert low["next_action_hint"] != high["next_action_hint"]+++def test_adversarial_duplicate_evidence_survives_once_with_exact_recovery():+ raw = _raw("low")+ raw["retrieval"] *= 3+ raw["quotes"] *= 3+ raw["symbol_bodies"] *= 3+ raw["best_guesses"] *= 3+ raw["code_rationale"] *= 3+ raw["candidates"] *= 3+ raw["fallback_targets"] *= 3+ raw["citations"] *= 3++ compact = project_answer_payload(raw, question="how does auth work", scope="src/auth")+ expanded = project_answer_payload(+ raw,+ question="how does auth work",+ scope="src/auth",+ include=["evidence"],+ )++ serialized = json.dumps(expanded, separators=(",", ":"), default=str)+ assert serialized.count("def check():\\n return True") == 1+ assert "quotes" not in expanded and "code_rationale" not in expanded+ assert expanded["citations"] == ["src/auth/service.py"]+ assert "fallback_targets" not in expanded+ assert expanded["candidates"] == [{"path": "src/auth/routes.py"}]+ assert expanded["citations_total"] == 3+ assert expanded["citations_emitted"] == 1+ assert compact["retrieval_total"] == 6+ assert compact["retrieval_emitted"] == 0+ assert compact["retrieval_reduced_reason"] == "confidence_projection_and_deduplication"+ assert compact["_meta"]["projection"]["recovery"] == {+ "tool": "get_answer",+ "arguments": {+ "question": "how does auth work",+ "include": ["evidence"],+ "scope": "src/auth",+ },+ }+ assert expanded["retrieval"], "the advertised one-call expansion must recover evidence"+++def test_expanded_projection_preserves_distinct_evidence_from_the_same_path():+ raw = _raw("low")+ for key in ("symbol_bodies", "quotes", "code_rationale", "best_guesses"):+ raw[key] = []+ raw["retrieval"].append(+ {+ "path": "src/auth/middleware.py",+ "excerpt": "middleware rejects a missing token",+ }+ )++ expanded = project_answer_payload(+ raw, question="how does auth work", include=["evidence"]+ )++ middleware = [+ row for row in expanded["retrieval"] if row["path"] == "src/auth/middleware.py"+ ]+ assert len(middleware) == 2+ assert {row["excerpt"] for row in middleware} == {+ "check()",+ "middleware rejects a missing token",+ }+++def test_symbol_qualified_evidence_deduplicates_file_navigation():+ raw = _raw("low")+ raw["citations"] = []+ raw["symbol_bodies"] = []+ raw["quotes"] = []+ raw["code_rationale"] = []+ raw["best_guesses"] = []+ raw["retrieval"] = [+ {+ "path": "src/auth/middleware.py::check",+ "file": "src/auth/middleware.py",+ "excerpt": "def check(): ...",+ }+ ]+ raw["fallback_targets"] = ["src/auth/middleware.py"]+ raw["candidates"] = [{"path": "src/auth/middleware.py"}]++ expanded = project_answer_payload(+ raw, question="where is check", include=["evidence"]+ )++ assert "fallback_targets" not in expanded+ assert "candidates" not in expanded+++def test_expanded_degraded_answer_names_only_retained_blocks():+ raw = _raw("low")+ raw.update(+ {+ "degraded": "no-llm-provider",+ "answer": "raw summary names retrieval, fallback_targets, and candidates",+ }+ )++ expanded = project_answer_payload(+ raw, question="how does auth work", include=["evidence"]+ )++ assert "fallback_targets" not in expanded+ assert "symbol_bodies" in expanded+ assert "fallback_targets" not in expanded["answer"]+ assert "candidates" not in expanded["answer"]+++def test_rationale_only_degraded_answer_leads_with_the_local_conclusion():+ raw = {+ "answer": "generic fallback",+ "citations": ["src/cache.py"],+ "confidence": "low",+ "degraded": "no-llm-provider",+ "code_rationale": [+ {+ "path": "src/cache.py",+ "lines": [4, 5],+ "comment": "The TTL matches the upstream feed's five-minute refresh.",+ }+ ],+ "_meta": {"contract_version": 1},+ }++ result = project_answer_payload(raw, question="why is the TTL five minutes")++ assert "upstream feed" in result["answer"]+ assert "src/cache.py" in result["answer"]+ assert result["confidence"] == "low"+++ ("provider", "legs", "expected_degraded"),+ [+ (None, {"fts": "ok", "vector": "keyless"}, "no-llm-provider"),+ (_Provider("", fail=True), {"fts": "ok", "vector": "ok"}, "synthesis-failed"),+ (None, {"fts": "ok", "vector": "error"}, "no-llm-provider"),+ ],+)+async def test_no_llm_and_failed_legs_remain_compact_and_actionable(+ setup_mcp, monkeypatch, provider, legs, expected_degraded+):+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import get_answer, tool_middleware++ _patch_retrieval(monkeypatch, answer_mod)+ monkeypatch.setattr(answer_mod, "_resolve_provider_for_answer", lambda _path: provider)+ monkeypatch.setattr(answer_mod, "_retrieval_legs", lambda: legs)+ monkeypatch.setattr(+ answer_mod,+ "_degraded_legs",+ lambda state: [name for name, status in state.items() if status == "error"],+ )++ result = await tool_middleware(get_answer)(+ f"how does auth work in {expected_degraded} {legs['vector']} mode"+ )++ assert result["degraded"] == expected_degraded+ assert result["answer"]+ assert result["next_action_hint"]+ assert result.get("best_guesses") or result.get("symbol_bodies") or result.get("retrieval")+ assert len(json.dumps(result, separators=(",", ":"), default=str)) < 24_000+ if legs["vector"] == "error":+ assert result["_meta"]["retrieval_degraded"] == ["vector"]+++async def test_real_embedding_failure_keeps_fts_evidence_in_final_projection(+ setup_mcp, monkeypatch+):+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import _answer_pipeline, get_answer, tool_middleware++ class Fts:+ async def search(self, _query, limit=15):+ return [+ SimpleNamespace(+ page_id=hit["page_id"],+ title=hit["page_id"],+ snippet="lexical authentication evidence",+ page_type="file_page",+ )+ for hit in _HITS[:limit]+ ]++ class FailingVectorStore:+ async def embed_texts(self, _texts):+ raise RuntimeError("embedding provider unavailable")++ async def search(self, _query, limit=15):+ raise RuntimeError("embedding provider unavailable")++ ctx = await answer_mod._resolve_repo_context()+ ctx.fts = Fts()+ ctx.vector_store = FailingVectorStore()+ ctx.vector_store_ready = None++ async def resolve(_repo=None):+ return ctx++ monkeypatch.setattr(answer_mod, "_resolve_repo_context", resolve)+ monkeypatch.setattr(answer_mod, "_hybrid_retrieve", _answer_pipeline.hybrid_retrieve)+ _patch_retrieval(monkeypatch, answer_mod)+ monkeypatch.setattr(answer_mod, "_hybrid_retrieve", _answer_pipeline.hybrid_retrieve)+ monkeypatch.setattr(answer_mod, "_resolve_provider_for_answer", lambda _path: None)++ result = await tool_middleware(get_answer)("how does auth work if embeddings fail")++ assert result["answer"]+ assert result.get("best_guesses") or result.get("retrieval")+ assert "embed" in result["_meta"]["retrieval_degraded"]+ assert "vector" in result["_meta"]["retrieval_degraded"]+ assert len(json.dumps(result, separators=(",", ":"), default=str)) < 24_000+++async def test_missing_generated_docs_can_fall_back_to_local_symbol_evidence(+ setup_mcp, monkeypatch+):+ import repowise.server.mcp_server.tool_answer.answer as answer_mod+ from repowise.server.mcp_server import get_answer, tool_middleware++ async def no_pages(question, ctx):+ return []++ async def hydrate_empty(hits, ctx, *, scope=None):+ return hits++ async def anchor_symbol(session, repo_id, names, hits, **kwargs):+ return (+ [+ {+ "page_id": "symbol:AuthService",+ "target_path": "src/auth/service.py",+ "title": "AuthService",+ "summary": "Local indexed symbol",+ "snippet": "class AuthService",+ "excerpt": "class AuthService",+ "page_type": "symbol_spotlight",+ "score": 6.0,+ }+ ],+ {"union": {}, "qualified_miss": []},+ )++ monkeypatch.setattr(answer_mod, "_hybrid_retrieve", no_pages)+ monkeypatch.setattr(answer_mod, "_hydrate_hits", hydrate_empty)+ monkeypatch.setattr(answer_mod, "_anchor_symbol_hits", anchor_symbol)+ monkeypatch.setattr(answer_mod, "_resolve_provider_for_answer", lambda _path: None)++ result = await tool_middleware(get_answer)("where is AuthService defined")++ assert result["answer"]+ assert result["best_guesses"][0]["file"] == "src/auth/service.py"+ assert result["next_action_hint"]diff --git a/tests/unit/server/mcp/test_budget.py b/tests/unit/server/mcp/test_budget.pyindex 2b8b12a95..5ac2d7099 100644--- a/tests/unit/server/mcp/test_budget.py+++ b/tests/unit/server/mcp/test_budget.py@@ -368,6 +368,33 @@ def test_fit_to_budget_reports_total_emitted_and_reason(repo_root: Path):assert response["results_omitted"] == 6 - len(response["results"])+def test_fit_to_budget_preserves_projection_reason_and_persisted_omission_count(+ repo_root: Path,+):+ response = {+ "results": [{"row": i, "body": "r" * 1000} for i in range(3)],+ "results_total": 8,+ "results_emitted": 3,+ "results_reduced_reason": "confidence_projection_and_deduplication",+ }+ collector = OmissionCollector("get_answer", repo_root=repo_root)++ fit_to_budget(+ response,+ ("results[]",),+ collector,+ char_budget=2200,+ headroom=0,+ record_counts=True,+ )+ collector.attach(response)++ assert response["results_total"] == 8+ assert response["results_emitted"] == len(response["results"])+ assert response["results_reduced_reason"].endswith("_and_response_budget")+ assert response["results_omitted"] == 3 - len(response["results"])++def test_fit_to_budget_can_reduce_a_ranked_mapping(repo_root: Path):response = {"targets": {f"src/{i}.py": {"body": "x" * 1000} for i in range(6)}}collector = OmissionCollector("get_risk", repo_root=repo_root)@@ -542,20 +569,20 @@ async def test_get_overview_stays_under_a_narrowed_host_cap(budgeted = tool_middleware(get_overview)full = await budgeted()assert "truncated" not in full # normal cap: nothing sheds- assert full["tool_guide"]+ assert full["tool_surface"]["recipes"]monkeypatch.setenv("MAX_MCP_OUTPUT_TOKENS", "700")trimmed = await budgeted()assert trimmed["truncated"] is True- assert "tool_guide" not in trimmed # first in the declared shed order+ assert not trimmed.get("tool_surface", {}).get("recipes")assert trimmed["title"] == full["title"]accounting = trimmed["_meta"]["response_budget"]assert len(json.dumps(trimmed, separators=(",", ":"), default=str)) <= accounting["limit_chars"]stored = _joined(repo_root, trimmed["_meta"]["omitted"]["refs"])- assert "first_call" in stored+ assert "answer_question" in storeddef test_risk_trim_blast_lists_collects_drops(repo_root: Path):diff --git a/tests/unit/server/mcp/test_mcp_exclude_filter_context_answer.py b/tests/unit/server/mcp/test_mcp_exclude_filter_context_answer.pyindex b81af2832..4de1ff5a7 100644--- a/tests/unit/server/mcp/test_mcp_exclude_filter_context_answer.py+++ b/tests/unit/server/mcp/test_mcp_exclude_filter_context_answer.py@@ -178,7 +178,7 @@ async def test_get_answer_filters_excluded_hits(setup_mcp, monkeypatch):best = [g.get("file") for g in result.get("best_guesses", [])]assert "src/db/models.py" not in best# The non-excluded hit survives.- assert "src/auth/service.py" in result.get("fallback_targets", [])+ assert "src/auth/service.py" in best@pytest.mark.asynciodiff --git a/tests/unit/server/mcp/test_overview_surface.py b/tests/unit/server/mcp/test_overview_surface.pynew file mode 100644index 000000000..fafa18eba--- /dev/null+++ b/tests/unit/server/mcp/test_overview_surface.py@@ -0,0 +1,190 @@+"""Registry-selected ``get_overview`` tool descriptions and recipes."""++from __future__ import annotations++import ast+import inspect+import json++import pytest++from repowise.core.registry import ToolEntry, ToolRecipe+from repowise.server.mcp_server._tool_selection import (+ registry_tool_rows,+ resolve_enabled_tools,+)+from repowise.server.mcp_server.tool_overview import _tool_surface_guide+++def _fn(name: str):+ def tool():+ """Fixture tool description."""++ tool.__name__ = name+ return tool+++_ENTRIES = [+ ToolEntry(+ _fn("get_answer"),+ "get_answer",+ recipes=(+ ToolRecipe(+ "answer_question",+ 'get_answer(question="how does X work?")',+ ("get_answer",),+ ),+ ),+ surface_order=10,+ ),+ ToolEntry(+ _fn("get_context"),+ "get_context",+ recipes=(+ ToolRecipe(+ "read_file_shape",+ 'get_context(targets=["path"], include=["skeleton"])',+ ("get_context",),+ ),+ ),+ surface_order=20,+ ),+ ToolEntry(_fn("get_overview"), "get_overview", surface_order=80),+ ToolEntry(+ _fn("list_repos"),+ "list_repos",+ tier="utility",+ requires_workspace=True,+ surface_order=110,+ ),+ ToolEntry(+ _fn("get_dependency_path"),+ "get_dependency_path",+ default=False,+ tier="specialist",+ surface_order=220,+ ),+ ToolEntry(+ _fn("get_blast_radius"),+ "get_blast_radius",+ default=False,+ requires_workspace=True,+ tier="specialist",+ surface_order=230,+ ),+]+++def _guide(*, workspace: bool, override=None):+ rows = registry_tool_rows(_ENTRIES)+ enabled = resolve_enabled_tools(_ENTRIES, is_workspace=workspace, override=override)+ return _tool_surface_guide(+ is_workspace=workspace,+ rows=rows,+ enabled_names=enabled,+ )+++ ("workspace", "override", "expected"),+ [+ (False, None, {"get_answer", "get_context", "get_overview"}),+ (True, None, {"get_answer", "get_context", "get_overview", "list_repos"}),+ (False, "lean", {"get_answer", "get_context"}),+ (False, "get_overview,get_dependency_path", {"get_overview", "get_dependency_path"}),+ (+ False,+ "+get_dependency_path",+ {"get_answer", "get_context", "get_overview", "get_dependency_path"},+ ),+ ],+)+def test_selected_surface_variants_are_explicit_and_recipe_safe(+ workspace, override, expected+):+ guide = _guide(workspace=workspace, override=override)++ assert guide["mode"] == ("workspace" if workspace else "single_repo")+ assert set(guide["enabled"]) == expected+ assert guide["counts"]["enabled"] == len(expected)+ assert all(row["name"] in expected for row in guide["tools"])+ assert all(row["description"] for row in guide["tools"])+ assert all(row["name"] not in guide["enabled"] or row["enabled"] for row in guide["opt_in"])+ recipe_calls = [recipe["call"] for recipe in guide["recipes"]]+ assert all(call.split("(", 1)[0] in expected for call in recipe_calls)+ if "get_answer" not in expected:+ assert not any(call.startswith("get_answer(") for call in recipe_calls)+++ ("include", "expected"),+ [+ (["content"], "content_md"),+ (["outline"], "outline"),+ (["tour"], "reading_order"),+ (["decisions"], "key_decisions"),+ (["graph"], "community_summary"),+ (["ownership"], "knowledge_map"),+ ],+)+async def test_each_explicit_overview_projection_is_bounded(+ setup_mcp, include, expected+):+ from repowise.server.mcp_server import get_overview, tool_middleware++ result = await tool_middleware(get_overview)(include=include)+ size = len(json.dumps(result, separators=(",", ":"), default=str))++ assert result["_meta"]["response_budget"]["tier"] == "expanded"+ assert size <= 32_000+ # Empty fixture data may make an optional block absent, but the projection+ # must remain a valid expanded call and must never call it an omission.+ if expected in result:+ assert result[expected] is not None+ assert result.get("_meta", {}).get("projection") is None+++async def test_default_and_combined_overview_payloads_fit(setup_mcp):+ from repowise.server.mcp_server import get_overview, tool_middleware++ call = tool_middleware(get_overview)+ default = await call()+ combined = await call(+ include=["content", "outline", "tour", "decisions", "graph", "ownership"]+ )++ assert len(json.dumps(default, separators=(",", ":"), default=str)) <= 24_000+ assert len(json.dumps(combined, separators=(",", ":"), default=str)) <= 32_000+ assert default["tool_surface"]["recipes"]+ assert "tool_guide" not in default+++async def test_live_registry_recipe_calls_bind_to_current_tool_signatures(setup_mcp):+ from repowise.core.registry import mcp_tool_registry+ from repowise.server.mcp_server import get_overview, tool_middleware++ result = await tool_middleware(get_overview)()+ entries = {entry.name: entry for entry in mcp_tool_registry.entries()}+ recipe_requirements = {+ recipe.name: set(recipe.requires)+ for entry in entries.values()+ for recipe in entry.recipes+ }++ for recipe in result["tool_surface"]["recipes"]:+ expression = ast.parse(recipe["call"], mode="eval").body+ assert isinstance(expression, ast.Call)+ assert isinstance(expression.func, ast.Name)+ entry = entries[expression.func.id]+ kwargs = {+ keyword.arg: ast.literal_eval(keyword.value)+ for keyword in expression.keywords+ if keyword.arg is not None+ }+ inspect.signature(entry.fn).bind(**kwargs)+ assert recipe_requirements[recipe["name"]] <= set(+ result["tool_surface"]["enabled"]+ )