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.

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__.py
index 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.py
index 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 Any
TOOL_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 = 1000
trust_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.py
index 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_total
container[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"] = total
container[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)
return
if 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.py
index 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.py
index 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 inspect
import logging
from collections.abc import Iterable, Sequence
from 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.py
index 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 time
from typing import NamedTuple
from repowise.core.persistence.database import get_session
+from repowise.core.registry import ToolRecipe
from repowise.core.registry import mcp_tool_registry as mcp
from 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_answer
from 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 correction
of 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.py
index 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.py
index 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.py
new file mode 100644
index 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.py
index 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 logging
from typing import Any
from repowise.core.persistence.database import get_session
+from repowise.core.registry import ToolRecipe
from repowise.core.registry import mcp_tool_registry as mcp
from repowise.server.mcp_server import _state
from 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.py
index 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 = None
if 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.py
index 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 ToolRecipe
from repowise.core.registry import mcp_tool_registry as mcp
from repowise.server.mcp_server._budget import OmissionCollector
from 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.py
index 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 ToolRecipe
from repowise.core.registry import mcp_tool_registry as mcp
from repowise.core.test_paths import is_test_path, is_test_related_path
from 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.py
index 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_currency
from repowise.core.providers.embedding import store_has_semantic_vectors
+from repowise.core.registry import ToolRecipe
from repowise.core.registry import mcp_tool_registry as mcp
from 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.py
index 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.py
index 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, mon
top = 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.py
index 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 note
assert "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.py
index 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_payload
def _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" * 1500
payload = 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 external
async 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.py
index 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.py
new file mode 100644
index 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.py
index 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 stored
def 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.py
index 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.asyncio
diff --git a/tests/unit/server/mcp/test_overview_surface.py b/tests/unit/server/mcp/test_overview_surface.py
new file mode 100644
index 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"]
+ )