Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(mcp): enforce canonical response budgets at delivery (#1916)
Raghav Chamadiya02e3d1eb7584
diff --git a/packages/server/src/repowise/server/mcp_server/__init__.py b/packages/server/src/repowise/server/mcp_server/__init__.pyindex f8bc05f89..ecc803a4d 100644--- a/packages/server/src/repowise/server/mcp_server/__init__.py+++ b/packages/server/src/repowise/server/mcp_server/__init__.py@@ -93,24 +93,32 @@ def tool_middleware(fn: Any) -> Any:1. ``shield`` — no exception may escape to FastMCP as a protocol-levelisError (an early isError teaches the agent to abandon the server forthe whole session), so it must see the raw tool.- 2. ``quantize`` — rounds every float in the response. Outside the shield so+ 2. ``trust`` — adds the final transport trust envelope.+ 3. ``quantize`` — rounds every float in the response. Outside the shield soshaped error responses are covered too, and inside the savings layer sothe ledger measures the payload as actually delivered.- 3. ``instrument`` — savings/telemetry, outermost, so shaped error responses- are still dead-end-debited in the ledger.+ 4. ``budget`` — caps the delivered shape before savings are measured.+ 5. ``instrument`` — records the bounded result and adds savings metadata.+ 6. ``budget`` — accounts for those final middleware fields and rechecks.Named rather than inlined at the ``apply`` call so tests can wrap a tool inthe real composition; ``tests/unit/server/mcp/test_number_precision.py``relies on that to prove no raw double reaches an agent."""+ import inspectfrom functools import wraps+ from repowise.server.mcp_server._budget import (+ enforce_response_budget,+ resolve_response_budget_repo_root,+ )from repowise.server.mcp_server._failure_shield import shieldfrom repowise.server.mcp_server._meta import finalize_trust_envelopefrom repowise.server.mcp_server._rounding import quantizefrom repowise.server.mcp_server._savings import instrumentevidence_kind = getattr(fn, "__repowise_trust_kind__", None)+ signature = inspect.signature(fn)def trust(inner: Any) -> Any:@wraps(inner)@@ -121,7 +129,31 @@ def tool_middleware(fn: Any) -> Any:return wrapped- return instrument(quantize(trust(shield(fn))))+ def budget(inner: Any) -> Any:+ @wraps(inner)+ async def wrapped(*args: Any, **kwargs: Any) -> Any:+ repo_root = await resolve_response_budget_repo_root(signature, args, kwargs)+ result = enforce_response_budget(+ fn.__name__,+ await inner(*args, **kwargs),+ signature=signature,+ args=args,+ kwargs=kwargs,+ repo_root=repo_root,+ )+ result = finalize_trust_envelope(result, evidence_kind=evidence_kind)+ return enforce_response_budget(+ fn.__name__,+ result,+ signature=signature,+ args=args,+ kwargs=kwargs,+ repo_root=repo_root,+ )++ return wrapped++ return budget(instrument(budget(quantize(trust(shield(fn))))))def ensure_full_surface() -> Any:diff --git a/packages/server/src/repowise/server/mcp_server/_budget/__init__.py b/packages/server/src/repowise/server/mcp_server/_budget/__init__.pyindex 0b6abf59d..a1c249e5c 100644--- a/packages/server/src/repowise/server/mcp_server/_budget/__init__.py+++ b/packages/server/src/repowise/server/mcp_server/_budget/__init__.py@@ -34,19 +34,31 @@ from repowise.server.mcp_server._budget.budgeter import (truncate_to_budget,)from repowise.server.mcp_server._budget.collector import OmissionCollector+from repowise.server.mcp_server._budget.contracts import (+ DEFAULT_RESPONSE_CHARS,+ EXPANDED_RESPONSE_CHARS,+ budgeted_tool_names,+ enforce_response_budget,+ resolve_response_budget_repo_root,+)__all__ = ["CHARS_PER_TOKEN","CHAR_BUDGET",+ "DEFAULT_RESPONSE_CHARS",+ "EXPANDED_RESPONSE_CHARS","FIT_HEADROOM_CHARS","HOST_CAP_BUDGET_FRACTION","HOST_MCP_TOKEN_CAP_DEFAULT","TOKEN_BUDGET","OmissionCollector",+ "budgeted_tool_names","effective_char_budget",+ "enforce_response_budget","estimate_response_tokens","fit_to_budget","host_token_cap","over_budget",+ "resolve_response_budget_repo_root","truncate_to_budget",]diff --git a/packages/server/src/repowise/server/mcp_server/_budget/budgeter.py b/packages/server/src/repowise/server/mcp_server/_budget/budgeter.pyindex 165d54658..7d6c18f8e 100644--- a/packages/server/src/repowise/server/mcp_server/_budget/budgeter.py+++ b/packages/server/src/repowise/server/mcp_server/_budget/budgeter.py@@ -107,9 +107,15 @@ def response_chars(response: Any) -> int:return len(json.dumps(response, separators=(",", ":"), default=str))-def over_budget(response: Any, *, headroom: int = FIT_HEADROOM_CHARS) -> bool:+def over_budget(+ response: Any,+ *,+ headroom: int = FIT_HEADROOM_CHARS,+ char_budget: int | None = None,+) -> bool:"""True when *response* would exceed the transport ceiling once markers land."""- return response_chars(response) > effective_char_budget() - headroom+ budget = effective_char_budget() if char_budget is None else char_budget+ return response_chars(response) > budget - headroomdef fit_to_budget(@@ -118,6 +124,8 @@ def fit_to_budget(collector: OmissionCollector,*,headroom: int = FIT_HEADROOM_CHARS,+ char_budget: int | None = None,+ record_counts: bool = False,) -> dict[str, Any]:"""Shed whole blocks named by *order* until *response* fits the budget.@@ -132,7 +140,7 @@ def fit_to_budget(which is what ``headroom`` reserves for."""for key in order:- if not over_budget(response, headroom=headroom):+ if not over_budget(response, headroom=headroom, char_budget=char_budget):breakcontainer, _, leaf = key.rpartition(".")target: Any = response@@ -141,9 +149,21 @@ def fit_to_budget(if not isinstance(target, dict):continueif leaf.endswith("[]"):- _shed_tail(response, target, leaf[:-2], key[:-2], collector, headroom)+ _shed_tail(+ response,+ target,+ leaf[:-2],+ key[:-2],+ collector,+ headroom,+ char_budget,+ record_counts,+ )elif target.get(leaf):- collector.add(key, target.pop(leaf))+ value = target.pop(leaf)+ collector.add(key, value)+ if record_counts:+ _record_reduction(response, target, key, leaf, value, emitted=0)response["truncated"] = Truereturn response@@ -155,19 +175,77 @@ def _shed_tail(label: str,collector: OmissionCollector,headroom: int,+ char_budget: int | None,+ record_counts: bool,) -> None:"""Drop ranked rows from the tail of ``container[leaf]`` until it fits."""rows = container.get(leaf)- if not isinstance(rows, list):+ if not isinstance(rows, (list, dict)):return+ total = len(rows)dropped: list[Any] = []- while len(rows) > 1 and over_budget(response, headroom=headroom):- dropped.append(rows.pop())+ while len(rows) > 1 and over_budget(+ response, headroom=headroom, char_budget=char_budget+ ):+ if isinstance(rows, list):+ dropped.append(rows.pop())+ else:+ name = next(reversed(rows))+ dropped.append({name: rows.pop(name)})if dropped:collector.add(label, list(reversed(dropped)))+ if record_counts:+ 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}_truncated"] = True+ container[f"{leaf}_omitted"] = collection_total - len(rows)response["truncated"] = True+def _record_reduction(+ response: dict[str, Any],+ container: dict[str, Any],+ path: str,+ field: str,+ value: Any,+ *,+ emitted: int,+) -> None:+ """Keep honest counts for a collection removed as one budget block."""+ if isinstance(value, list):+ 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}_truncated"] = True+ container[f"{field}_omitted"] = total - emitted+ return+ if not isinstance(value, dict):+ return++ reductions = response.setdefault("_meta", {}).setdefault("reductions", [])++ def visit(node: Any, node_path: str) -> None:+ if isinstance(node, list):+ reductions.append(+ {+ "field": node_path,+ "total": len(node),+ "emitted": 0,+ "reason": "response_budget",+ }+ )+ elif isinstance(node, dict):+ for name, child in node.items():+ visit(child, f"{node_path}.{name}")++ visit(value, path)++# 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.@@ -225,6 +303,7 @@ def truncate_to_budget(char_budget: int | None = None,*,collector: OmissionCollector | None = None,+ record_counts: bool = False,) -> dict[str, Any]:"""Cap a targets-shaped response at roughly ``TOKEN_BUDGET`` tokens.@@ -254,8 +333,10 @@ def truncate_to_budget(With a *collector*, every dropped piece of content is also captured andpersisted, and the response gains ``omission_marker`` + ``_meta.omitted``- (see :class:`OmissionCollector`). Without one, behaviour is byte-identical- to the original silent-drop implementation.+ (see :class:`OmissionCollector`). ``record_counts`` adds the shared+ ``*_total`` / emitted / reason fields for final-delivery accounting. With+ neither option, behaviour is byte-identical to the original silent-drop+ implementation.Edge cases:* Empty ``targets`` → returns unchanged with ``truncated=False``.@@ -268,7 +349,7 @@ def truncate_to_budget(if char_budget is None:char_budget = effective_char_budget()try:- result = _run_stages(result, char_budget, collector)+ result = _run_stages(result, char_budget, collector, record_counts)finally:if collector is not None:collector.attach(result)@@ -300,12 +381,14 @@ def _run_stages(result: dict[str, Any],char_budget: int,collector: OmissionCollector | None,+ record_counts: bool,) -> dict[str, Any]:result.setdefault("truncated", False)result.setdefault("dropped_targets", [])result.setdefault("dropped_symbols", {})targets: dict[str, Any] = result.get("targets") or {}+ targets_total = len(targets)if not targets:return result@@ -401,12 +484,14 @@ def _run_stages(else:dropped.append(sym.get("name") or "<anonymous>")dropped_syms.append(sym)+ symbol_content_reduced = Falseif not kept and ordered:# Edge case: a single symbol is larger than the budget. Keep one# (truncating its docstring) rather than returning zero symbols —# the caller at least learns the target resolved.head = dict(ordered[0])if isinstance(head.get("docstring"), str):+ symbol_content_reduced = len(head["docstring"]) > 200head["docstring"] = head["docstring"][:200]kept = [head]dropped = [s.get("name") or "<anonymous>" for s in ordered[1:]]@@ -414,8 +499,15 @@ def _run_stages(# original alongside the genuinely dropped tail.dropped_syms = list(ordered)docs["symbols"] = kept- if dropped:- result["dropped_symbols"][tgt_name] = dropped+ if dropped or symbol_content_reduced:+ if record_counts:+ docs["symbols_total"] = max(+ len(ordered), int(docs.get("symbols_total") or 0)+ )+ docs["symbols_emitted"] = len(kept)+ docs["symbols_reduced_reason"] = "response_budget"+ if dropped:+ result["dropped_symbols"][tgt_name] = droppedresult["truncated"] = Trueif collector is not None and dropped_syms:collector.add(@@ -448,6 +540,12 @@ def _run_stages(collector.add(f"dropped target {name}", evicted)result["dropped_targets"].append(name)result["truncated"] = True+ if record_counts:+ result["targets_total"] = max(+ targets_total, int(result.get("targets_total") or 0)+ )+ result["targets_emitted"] = len(targets)+ result["targets_reduced_reason"] = "response_budget"if _size() <= char_budget:breakdiff --git a/packages/server/src/repowise/server/mcp_server/_budget/collector.py b/packages/server/src/repowise/server/mcp_server/_budget/collector.pyindex 09184ec68..0ba65d71c 100644--- a/packages/server/src/repowise/server/mcp_server/_budget/collector.py+++ b/packages/server/src/repowise/server/mcp_server/_budget/collector.py@@ -43,6 +43,7 @@ _RESTORE_HINT = ()_DOC_SECTION_RULE = "==== {label} ===="+_OMISSION_DOC_CHARS = 28_000def render_chunk(label: str, value: Any) -> str:@@ -135,16 +136,34 @@ class OmissionCollector:try:if self._chunks:doc = self._render_doc()- ref = self._put(doc)- if ref is not None:- tokens = sum(estimate_tokens(text) for _, text in self._chunks)- self._omitted_tokens += tokens- response["omission_marker"] = render_marker(ref, doc.count("\n") + 1, tokens)+ markers: list[str] = []+ for start in range(0, len(doc), _OMISSION_DOC_CHARS):+ part = doc[start : start + _OMISSION_DOC_CHARS]+ ref = self._put(part)+ if ref is not None:+ tokens = estimate_tokens(part)+ self._omitted_tokens += tokens+ markers.append(render_marker(ref, part.count("\n") + 1, tokens))+ if markers:+ response["omission_marker"] = markers[0]+ if len(markers) > 1:+ response["omission_markers"] = markers+ elif self._chunks:+ response.setdefault("_meta", {})["recovery_unavailable"] = (+ "Omission storage failed; dropped evidence could not be persisted."+ )if self._refs:meta = response.setdefault("_meta", {})+ existing = meta.get("omitted")+ existing_refs = (+ list(existing.get("refs") or []) if isinstance(existing, dict) else []+ )+ existing_tokens = (+ int(existing.get("tokens") or 0) if isinstance(existing, dict) else 0+ )meta["omitted"] = {- "refs": list(self._refs),- "tokens": self._omitted_tokens,+ "refs": [*existing_refs, *self._refs],+ "tokens": existing_tokens + self._omitted_tokens,"restore": _RESTORE_HINT,}except Exception: # pragma: no cover - defensivediff --git a/packages/server/src/repowise/server/mcp_server/_budget/contracts.py b/packages/server/src/repowise/server/mcp_server/_budget/contracts.pynew file mode 100644index 000000000..1406013eb--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/_budget/contracts.py@@ -0,0 +1,330 @@+"""Product response budgets enforced at the final MCP result boundary.++Tools decide which evidence is cheapest to lose, but accounting, omission+storage, tier selection, and the final-size check live here. The middleware+calls :func:`enforce_response_budget` after trust metadata and float+quantisation have produced the object the MCP client will receive.+"""++from __future__ import annotations++import inspect+import json+from dataclasses import dataclass+from pathlib import Path+from typing import Any, Literal++from repowise.server.mcp_server._budget.budgeter import (+ effective_char_budget,+ fit_to_budget,+ response_chars,+ truncate_to_budget,+)+from repowise.server.mcp_server._budget.collector import OmissionCollector++DEFAULT_RESPONSE_CHARS = 24_000+EXPANDED_RESPONSE_CHARS = 32_000+_FINAL_HEADROOM_CHARS = 1_200+++@dataclass(frozen=True)+class ResponseBudgetContract:+ """One tool's priority projection under the shared response budget."""++ strategy: Literal["blocks", "targets"]+ shed_order: tuple[str, ...] = ()+ expansion_argument: str | None = "include"+ protected: tuple[str, ...] = ()+++_CONTRACTS: dict[str, ResponseBudgetContract] = {+ "get_context": ResponseBudgetContract("targets", protected=("targets",)),+ "get_risk": ResponseBudgetContract(+ "blocks",+ (+ "global_hotspots",+ "pr_blast_radius.guarding_tests",+ "pr_blast_radius",+ "directive.test_recommendations[]",+ "directive.tests_to_run[]",+ "directive.may_break[]",+ "targets[]",+ ),+ protected=("directive", "targets"),+ ),+ "get_change_risk": ResponseBudgetContract(+ "blocks",+ (+ "exclude_patterns",+ "prior_fixes",+ "impacted_tests",+ "cross_repo",+ "fix_history.files[]",+ "fix_history.files",+ ),+ protected=("classification", "risk_percentile", "risk_authority", "score"),+ ),+ "get_answer": ResponseBudgetContract(+ "blocks",+ (+ "episodes",+ "flow_path",+ "retrieval[]",+ "retrieval",+ "code_rationale",+ "quotes",+ "symbol_bodies[]",+ "symbol_bodies",+ "best_guesses[]",+ "best_guesses",+ "candidates[]",+ "candidates",+ "fallback_targets[]",+ "fallback_targets",+ ),+ expansion_argument=None,+ 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",+ "guided_tour_hint",+ "guided_tour",+ "reading_order_hint",+ "reading_order",+ "community_summary",+ "knowledge_map",+ "key_decisions",+ "outline_hint",+ "outline",+ "tool_surface",+ "repos[]",+ "key_modules[]",+ "content_md",+ ),+ protected=("title", "architecture", "entry_points"),+ ),+}+++def response_budget_shed_order(tool: str) -> tuple[str, ...]:+ """Return a tool's shared shed order for compatibility projections."""+ contract = _CONTRACTS.get(tool)+ return contract.shed_order if contract is not None else ()+++def _call_uses_expansion(+ contract: ResponseBudgetContract,+ signature: inspect.Signature,+ args: tuple[Any, ...],+ kwargs: dict[str, Any],+) -> bool:+ if contract.expansion_argument is None:+ return False+ try:+ bound = signature.bind_partial(*args, **kwargs)+ except TypeError:+ return bool(kwargs.get(contract.expansion_argument))+ return bool(bound.arguments.get(contract.expansion_argument))+++def _stamp_accounting(result: dict[str, Any], *, limit: int, tier: str) -> None:+ meta = result.setdefault("_meta", {})+ budget = meta.setdefault("response_budget", {})+ budget.update({"limit_chars": limit, "tier": tier, "serialized_chars": 0})+ for _ in range(3):+ measured = response_chars(result)+ if budget["serialized_chars"] == measured:+ break+ budget["serialized_chars"] = measured+++async def resolve_response_budget_repo_root(+ signature: inspect.Signature,+ args: tuple[Any, ...],+ kwargs: dict[str, Any],+) -> str | Path | None:+ """Resolve the selected repository so omission refs round-trip by alias."""+ try:+ bound = signature.bind_partial(*args, **kwargs)+ repo = bound.arguments.get("repo")+ if repo == "all":+ from repowise.server.mcp_server import _state++ return getattr(_state, "_workspace_root", None) or getattr(+ _state, "_repo_path", None+ )+ from repowise.server.mcp_server._helpers import _resolve_repo_context++ return (await _resolve_repo_context(repo)).path+ except Exception:+ from repowise.server.mcp_server import _state++ return getattr(_state, "_repo_path", None)+++def _emergency_fit(+ result: dict[str, Any],+ contract: ResponseBudgetContract,+ collector: OmissionCollector,+ limit: int,+) -> None:+ """Bound an unexpectedly huge protected core without a false fit claim."""+ protected = {*contract.protected, "_meta"}+ removable = [+ key+ for key in result+ if key not in protected+ and key not in {"truncated", "omission_marker"}+ and not key.endswith(("_total", "_emitted", "_reduced_reason"))+ ]+ for key in sorted(removable, key=lambda item: response_chars(result[item]), reverse=True):+ if response_chars(result) <= limit:+ return+ value = result.pop(key)+ collector.add(f"{key} removed by final budget guard", value)+ if isinstance(value, list):+ result[f"{key}_total"] = len(value)+ result[f"{key}_emitted"] = 0+ result[f"{key}_reduced_reason"] = "response_budget"+ result["truncated"] = True++ while response_chars(result) > limit:+ before = response_chars(result)+ candidates: list[tuple[int, dict[str, Any], str, str, Any]] = []++ def visit(+ value: Any,+ path: str,+ found: list[tuple[int, dict[str, Any], str, str, Any]],+ ) -> None:+ if not isinstance(value, dict):+ return+ for key, child in value.items():+ child_path = f"{path}.{key}" if path else key+ if child_path.startswith("_meta") or key.endswith(+ ("_total", "_emitted", "_reduced_reason")+ ):+ continue+ if isinstance(child, str) and len(child) > 800:+ found.append((len(child), value, key, child_path, child))+ elif isinstance(child, list) and child:+ found.append((response_chars(child), value, key, child_path, child))+ elif isinstance(child, dict):+ visit(child, child_path, found)++ visit(result, "", candidates)+ if not candidates:+ dictionaries = [+ (response_chars(result[key]), key, result[key])+ for key in contract.protected+ if isinstance(result.get(key), dict) and result[key]+ ]+ if not dictionaries:+ return+ _, key, value = max(dictionaries, key=lambda item: item[0])+ marker = collector.add_inline(+ f"{key} replaced by final budget guard",+ json.dumps(value, separators=(",", ":"), default=str),+ )+ result[key] = {+ "omission_ref": marker,+ "reduced_reason": "response_budget",+ }+ result["truncated"] = True+ if response_chars(result) >= before:+ return+ continue+ _, container, key, path, value = max(candidates, key=lambda item: item[0])+ if isinstance(value, list):+ dropped = value[len(value) // 2 :] if len(value) > 1 else value[:]+ kept = value[: len(value) // 2] if len(value) > 1 else []+ collector.add(f"{path} reduced by final budget guard", dropped)+ container[key] = kept+ container[f"{key}_total"] = max(+ len(value), int(container.get(f"{key}_total") or 0)+ )+ container[f"{key}_emitted"] = len(kept)+ container[f"{key}_reduced_reason"] = "response_budget"+ else:+ marker = collector.add_inline(path, value)+ suffix = f"\n{marker}" if marker else "\n[reduced to fit]"+ container[key] = value[: max(0, 800 - len(suffix))] + suffix+ result["truncated"] = True+ if response_chars(result) >= before:+ return+++def enforce_response_budget(+ tool: str,+ result: Any,+ *,+ signature: inspect.Signature,+ args: tuple[Any, ...],+ kwargs: dict[str, Any],+ repo_root: str | Path | None = None,+) -> Any:+ """Apply *tool*'s contract to its final, metadata-complete result."""+ contract = _CONTRACTS.get(tool)+ if contract is None or not isinstance(result, dict):+ return result++ if repo_root is None:+ from repowise.server.mcp_server import _state++ repo_root = getattr(_state, "_repo_path", None)++ expanded = _call_uses_expansion(contract, signature, args, kwargs)+ declared = EXPANDED_RESPONSE_CHARS if expanded else DEFAULT_RESPONSE_CHARS+ limit = effective_char_budget(declared)+ tier = "expanded" if expanded else "default"+ if result.get("truncated"):+ result.setdefault("_meta", {}).setdefault("state", {})["truncated"] = True+ _stamp_accounting(result, limit=limit, tier=tier)++ collector = OmissionCollector(tool, repo_root=repo_root)+ headroom = min(_FINAL_HEADROOM_CHARS, max(100, limit // 4))+ working_limit = max(1, limit - headroom)+ if contract.strategy == "targets":+ truncate_to_budget(+ result,+ char_budget=working_limit,+ collector=collector,+ record_counts=True,+ )+ else:+ fit_to_budget(+ result,+ contract.shed_order,+ collector,+ char_budget=working_limit,+ headroom=0,+ record_counts=True,+ )+ collector.attach(result)++ if response_chars(result) > limit:+ emergency = OmissionCollector(tool, repo_root=repo_root)+ _emergency_fit(result, contract, emergency, working_limit)+ emergency.attach(result)++ if result.get("truncated"):+ result.setdefault("_meta", {}).setdefault("state", {})["truncated"] = True+ _stamp_accounting(result, limit=limit, tier=tier)+ if response_chars(result) > limit:+ result.setdefault("_meta", {}).setdefault("response_budget", {})[+ "enforcement_error"+ ] = "protected response fields exceed the declared budget"+ _stamp_accounting(result, limit=limit, tier=tier)+ return result+++def budgeted_tool_names() -> frozenset[str]:+ """Names covered by the shared product response contract."""+ return frozenset(_CONTRACTS)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 16bc68c33..1062556d1 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@@ -385,6 +385,9 @@ 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.+Args:question: developer question.scope: optional path-prefix filter (e.g. "src/pkg/").diff --git a/packages/server/src/repowise/server/mcp_server/tool_change_risk.py b/packages/server/src/repowise/server/mcp_server/tool_change_risk.pyindex 0c4f24e11..a6bfa7fd0 100644--- a/packages/server/src/repowise/server/mcp_server/tool_change_risk.py+++ b/packages/server/src/repowise/server/mcp_server/tool_change_risk.py@@ -21,7 +21,8 @@ from repowise.core.analysis.change_risk import ()from repowise.core.analysis.pr_blast import rank_tests_by_reachfrom repowise.core.registry import mcp_tool_registry as mcp-from repowise.server.mcp_server._budget import OmissionCollector, fit_to_budget+from repowise.server.mcp_server._budget import OmissionCollector+from repowise.server.mcp_server._budget.contracts import response_budget_shed_orderfrom repowise.server.mcp_server._helpers import (_get_repo,_is_workspace_mode,@@ -47,21 +48,13 @@ _PRIOR_FIXES_LIMIT = 10_CROSS_REPO_BREAKING_LIMIT = 5_CROSS_REPO_CONSUMER_LIMIT = 10+# Compatibility projection for direct callers and older tests. The shared+# response contract remains the single source of truth for this order.+_SHED_ORDER = response_budget_shed_order("get_change_risk")+#: Per-field units and calibration. Identical on every call, so it is opt-in._INCLUDE_BLOCKS = frozenset({"scales"})-# Cheapest loss first; the score, its drivers and fix_history's numbers are the-# answer and never shed. cross_repo outlives the run-list: a test list is-# recoverable by running the suite, a broken consumer in another repo is not.-_SHED_ORDER: tuple[str, ...] = (- "exclude_patterns",- "prior_fixes",- "impacted_tests",- "cross_repo",- "fix_history.files",-)--@mcp.tool(surface_order=60)async def get_change_risk(revspec: str | None = None,@@ -86,8 +79,9 @@ async def get_change_risk(distinct, labels unavailable analysis, and exposes truncation metadata.``prior_fixes`` counts past fixes whose lines overlap this diff.- ``cross_repo`` names typed consumers and contract breaks from the last- workspace update.+ Defaults fit 24,000 chars; nonempty ``include`` uses 32,000. Reductions+ carry counts and recovery status in ``_meta``.+ Include-gated blocks are projections, not omissions.Args:revspec: Commit or ``base..head`` range to score. Omit it to score the@@ -168,7 +162,6 @@ async def get_change_risk(extra={"source": "live_git"},)attach_ignored_arguments(payload, ignored)- fit_to_budget(payload, _SHED_ORDER, collector)collector.attach(payload)return payloaddiff --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 a27a5e869..869de030d 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@@ -38,7 +38,6 @@ from typing import Anyfrom repowise.core.persistence.database import get_sessionfrom repowise.core.registry import mcp_tool_registry as mcpfrom repowise.server.mcp_server import _state-from repowise.server.mcp_server._budget import OmissionCollector, truncate_to_budgetfrom repowise.server.mcp_server._episodes import enrich_episode_counts as _enrich_episodesfrom repowise.server.mcp_server._helpers import (_get_exclude_spec,@@ -97,6 +96,11 @@ async def get_context(include=["skeleton"] for the whole file body-elided and line-verified inONE call, or Read it. Do not call get_symbol per signature.+ Default responses fit 24,000 serialized chars; nonempty ``include`` uses+ 32,000. Reductions carry counts and ``_meta.omitted`` recovery refs;+ ``_meta.recovery_unavailable`` names a storage failure.+ Include-gated blocks are projections, not omissions.+Args:targets: file paths, module paths, or "path::Symbol" ids.include: opt-in blocks: full_doc | ownership | last_change | callers@@ -234,12 +238,5 @@ async def get_context(if cross_repo:target_data["cross_repo"] = cross_repo- # Enforce the global token cap. Anything dropped is persisted via the- # collector so a truncated response always carries expandable- # ``[repowise#<ref>]`` markers instead of silently losing content.- collector = OmissionCollector("get_context", repo_root=ctx.path)- truncated = truncate_to_budget(response, collector=collector)- # After the cap, never before: a note about a dropped argument that the- # budget can itself drop is no note at all.- attach_ignored_arguments(truncated, ignored)- return truncated+ attach_ignored_arguments(response, ignored)+ return responsediff --git a/packages/server/src/repowise/server/mcp_server/tool_overview.py b/packages/server/src/repowise/server/mcp_server/tool_overview.pyindex 382ca27f8..8b688c0fb 100644--- a/packages/server/src/repowise/server/mcp_server/tool_overview.py+++ b/packages/server/src/repowise/server/mcp_server/tool_overview.py@@ -49,7 +49,7 @@ from repowise.core.persistence.models import ()from repowise.core.registry import mcp_tool_registry as mcpfrom repowise.server.mcp_server import _state-from repowise.server.mcp_server._budget import OmissionCollector, fit_to_budget+from repowise.server.mcp_server._budget import OmissionCollectorfrom repowise.server.mcp_server._helpers import (_get_exclude_spec,_get_repo,@@ -206,7 +206,6 @@ async def _workspace_overview() -> dict:collector = OmissionCollector("get_overview", repo_root=registry.workspace_root if registry else None)- fit_to_budget(result, _WORKSPACE_SHED_ORDER, collector, headroom=800)collector.attach(result)return result@@ -907,38 +906,6 @@ def _build_guided_tour(result.setdefault("architecture", {})["layer_order"] = layer_order-# Cheapest loss first. Everything not listed answers a question that changes an-# agent's next action, so it is never shed.-_WORKSPACE_SHED_ORDER: tuple[str, ...] = (- "cross_repo_topology",- "tool_surface.canonical",- "tool_surface.default",- "tool_surface.utilities",- "tool_surface.opt_in",- "repos[]",-)--_SHED_ORDER: tuple[str, ...] = (- "tool_guide",- "tool_surface.canonical",- "tool_surface.default",- "tool_surface.utilities",- "tool_surface.opt_in",- "guided_tour_hint",- "guided_tour",- "reading_order_hint",- "reading_order",- "community_summary",- "knowledge_map",- "key_decisions",- "outline_hint",- "outline",- "tool_surface",- "key_modules[]",- "content_md",-)--@mcp.tool(surface_order=80)async def get_overview(repo: str | None = None, include: list[str] | None = None) -> dict:"""Architecture map for an unfamiliar repo — first call when you don't know your way around.@@ -953,6 +920,10 @@ async def get_overview(repo: str | None = None, include: list[str] | None = Nonesection, and the outline, onboarding, ownership and graph blocks ship onlyon request. The response's ``more`` field names them.+ Defaults fit 24,000 chars; nonempty ``include`` uses 32,000. Reductions+ carry counts and recovery status in ``_meta``.+ Include-gated blocks are projections, not omissions.+In workspace mode:- Omit ``repo`` for the default repo's overview plus a workspace footer.- ``repo="all"`` returns the cross-repo topology (co-changes, package deps,@@ -1120,7 +1091,6 @@ async def get_overview(repo: str | None = None, include: list[str] | None = Noneresult["tool_surface"] = _tool_surface_guide(is_workspace=_state._registry is not None)result["_meta"] = _build_meta(repository=repository)- fit_to_budget(result, _SHED_ORDER, collector, headroom=800)collector.attach(result)return resultdiff --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 be5b32631..bec021bfc 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@@ -15,7 +15,7 @@ from repowise.core.persistence.models import (GraphNode,)from repowise.core.registry import mcp_tool_registry as mcp-from repowise.server.mcp_server._budget import OmissionCollector, fit_to_budget+from repowise.server.mcp_server._budget import OmissionCollectorfrom repowise.server.mcp_server._episodes import enrich_episode_counts as _enrich_episodesfrom repowise.server.mcp_server._helpers import (_get_exclude_spec,@@ -33,16 +33,6 @@ from .assessment import _assess_one_target, _get_active_contributor_count, fix_afrom .directives import _build_pr_directive, _governance_directivefrom .enrichment import _enrich_cross_repo, _enrich_health-# Cheapest loss first; the target cards and the directive are never shed.-# The directive retains its capped typed run list even if the larger blast-# dossier is shed to fit the transport budget.-_SHED_ORDER: tuple[str, ...] = (- "global_hotspots",- "pr_blast_radius.guarding_tests",- "pr_blast_radius",-)--#: Fields an agent cannot rank or act on: uncalibrated pagerank floats, and#: labels derived from numbers already printed beside them. Computed either way#: (``risk_summary`` reads them); ``include`` only decides whether they ship.@@ -112,11 +102,10 @@ async def get_risk(heuristic, never a runtime-breakage probability; ``overall_risk_score`` isits deprecated exact alias.- ``defect_profile`` appears only with counted fixes; ``top_symbols`` is- approximate attribution. ``episodes`` counts dated records bound to a- target, evidenced by a commit or a filesystem fact; ``get_why`` serves the- bodies. Directory targets aggregate everything beneath them, so compare- within a kind of target.+ Default responses fit 24,000 serialized chars; nonempty ``include`` uses+ 32,000. Reductions carry counts and ``_meta.omitted`` recovery refs;+ ``_meta.recovery_unavailable`` names a storage failure.+ Include-gated blocks are projections, not omissions.Args:targets: file paths to assess.@@ -308,6 +297,5 @@ async def get_risk()_drop_opt_in_blocks(response, include_set)attach_ignored_arguments(response, ignored)- fit_to_budget(response, _SHED_ORDER, collector)collector.attach(response)return responsediff --git a/tests/unit/server/mcp/test_budget.py b/tests/unit/server/mcp/test_budget.pyindex e0679fd60..2b8b12a95 100644--- a/tests/unit/server/mcp/test_budget.py+++ b/tests/unit/server/mcp/test_budget.py@@ -93,6 +93,22 @@ def test_collector_combined_doc_round_trip(repo_root: Path):assert _store_record(repo_root, ref)["source"] == "mcp:test_tool"+def test_collector_merges_existing_omission_refs(repo_root: Path):+ first = OmissionCollector("test_tool", repo_root=repo_root)+ first.add("first", "alpha")+ response: dict = {"_meta": {}}+ first.attach(response)++ second = OmissionCollector("test_tool", repo_root=repo_root)+ second.add("second", "beta")+ second.attach(response)++ refs = response["_meta"]["omitted"]["refs"]+ assert len(refs) == 2+ assert "alpha" in (_store_get(repo_root, refs[0]) or "")+ assert "beta" in (_store_get(repo_root, refs[1]) or "")++def test_collector_inline_marker_is_byte_identical(repo_root: Path):collector = OmissionCollector("test_tool", repo_root=repo_root)original = "def f():\n return 1\n\n# tail"@@ -122,6 +138,19 @@ def test_collector_store_failure_degrades_silently(tmp_path: Path):collector.attach(response)assert "omission_marker" not in responseassert "omitted" not in response["_meta"]+ assert "recovery_unavailable" in response["_meta"]+++def test_collector_chunks_large_recovery_documents(repo_root: Path):+ collector = OmissionCollector("test_tool", repo_root=repo_root)+ collector.add("large", "x" * 70_000)+ response: dict = {"_meta": {}}+ collector.attach(response)++ refs = response["_meta"]["omitted"]["refs"]+ assert len(refs) == 3+ assert len(response["omission_markers"]) == 3+ assert all(len(_store_get(repo_root, ref) or "") <= 28_000 for ref in refs)# ---------------------------------------------------------------------------@@ -228,6 +257,7 @@ def test_budgeter_decisions_unchanged_by_collector(repo_root: Path):# Strip the additive reversibility fields; the rest must be identical.collected.pop("omission_marker", None)+ collected.pop("omission_markers", None)collected["_meta"].pop("omitted", None)assert json.dumps(collected, sort_keys=True, default=str) == json.dumps(plain, sort_keys=True, default=str@@ -317,6 +347,45 @@ def test_fit_to_budget_trims_a_ranked_tail_but_never_empties_it(repo_root: Path,assert '"row": 5' in stored+def test_fit_to_budget_reports_total_emitted_and_reason(repo_root: Path):+ response = {"results": [{"row": i, "body": "r" * 1000} for i in range(6)]}+ 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"] == 6+ assert response["results_emitted"] == len(response["results"])+ assert response["results_reduced_reason"] == "response_budget"+ assert response["results_truncated"] is True+ assert response["results_omitted"] == 6 - 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)++ fit_to_budget(+ response,+ ("targets[]",),+ collector,+ char_budget=2200,+ headroom=0,+ record_counts=True,+ )++ assert response["targets_total"] == 6+ assert response["targets_emitted"] == len(response["targets"])+ assert response["targets_reduced_reason"] == "response_budget"++def _skeleton_response(text_chars: int = 12000) -> dict:return {"targets": {@@ -467,20 +536,24 @@ async def test_get_overview_stays_under_a_narrowed_host_cap():"""The ceiling is real end to end: no block of a live tool escapes it."""import repowise.server.mcp_server as mcp_mod- from repowise.server.mcp_server import get_overview+ from repowise.server.mcp_server import get_overview, tool_middlewaremcp_mod._repo_path = str(repo_root)- full = await get_overview()+ budgeted = tool_middleware(get_overview)+ full = await budgeted()assert "truncated" not in full # normal cap: nothing shedsassert full["tool_guide"]monkeypatch.setenv("MAX_MCP_OUTPUT_TOKENS", "700")- trimmed = await get_overview()+ trimmed = await budgeted()assert trimmed["truncated"] is Trueassert "tool_guide" not in trimmed # first in the declared shed orderassert trimmed["title"] == full["title"]- assert not over_budget(trimmed)+ 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 storeddiff --git a/tests/unit/server/mcp/test_response_budget_contracts.py b/tests/unit/server/mcp/test_response_budget_contracts.pynew file mode 100644index 000000000..56fbc48e5--- /dev/null+++ b/tests/unit/server/mcp/test_response_budget_contracts.py@@ -0,0 +1,254 @@+"""Golden contracts for the five shared-budget canonical MCP tools."""++from __future__ import annotations++import inspect+import json+from pathlib import Path+from typing import Any++import pytest++from repowise.core.distill.store import OmissionStore, default_store_path+from repowise.server.mcp_server import tool_middleware+from repowise.server.mcp_server._budget import (+ DEFAULT_RESPONSE_CHARS,+ EXPANDED_RESPONSE_CHARS,+ enforce_response_budget,+ resolve_response_budget_repo_root,+)+++def _payload(tool: str, pad: int) -> dict[str, Any]:+ rows = [{"id": i, "evidence": f"EVIDENCE_{tool}_{i}_" + "x" * pad} for i in range(3)]+ meta = {"contract_version": 1, "indexed_commit": "a" * 12}+ if tool == "get_context":+ return {+ "targets": {+ "src/large.py": {+ "target": "src/large.py",+ "type": "file",+ "docs": {"title": "Large", "content_md": rows[0]["evidence"], "symbols": rows},+ }+ },+ "_meta": meta,+ }+ if tool == "get_risk":+ return {+ "directive": {"tests_to_run": ["tests/test_large.py"], "summary": "review"},+ "targets": {"src/large.py": {"risk": "high", "summary": "inspect first"}},+ "pr_blast_radius": {"test_impact": rows, "evidence": rows[0]["evidence"]},+ "_meta": meta,+ }+ if tool == "get_change_risk":+ return {+ "classification": "elevated",+ "risk_percentile": 91.0,+ "fix_history": {"fix_count": 4, "files": rows},+ "prior_fixes": rows,+ "_meta": meta,+ }+ if tool == "get_answer":+ return {+ "answer": "The budget is applied after metadata.",+ "confidence": "high",+ "citations": ["src/large.py"],+ "retrieval": rows,+ "_meta": meta,+ }+ return {+ "title": "Large repository",+ "architecture": {"layers": [{"name": "Service", "file_count": 10}]},+ "tool_guide": {"details": rows[0]["evidence"]},+ "key_modules": rows,+ "_meta": meta,+ }+++def _signature() -> inspect.Signature:+ def call(include: list[str] | None = None) -> None:+ pass++ return inspect.signature(call)+++def _enforce(tool: str, payload: dict[str, Any], include: list[str] | None = None) -> dict:+ kwargs = {"include": include} if include is not None else {}+ return enforce_response_budget(+ tool,+ payload,+ signature=_signature(),+ args=(),+ kwargs=kwargs,+ )+++ ("tool", "required"),+ [+ ("get_context", "targets"),+ ("get_risk", "directive"),+ ("get_change_risk", "classification"),+ ("get_answer", "answer"),+ ("get_overview", "title"),+ ],+)[email protected](("case", "pad"), [("minimum", 0), ("typical", 600)])+def test_default_payload_goldens_keep_action_fields_and_exact_accounting(+ setup_mcp: str,+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+ tool: str,+ required: str,+ case: str,+ pad: int,+) -> None:+ import repowise.server.mcp_server as mcp_mod++ repo = tmp_path / case / tool+ (repo / ".repowise").mkdir(parents=True)+ monkeypatch.setattr(mcp_mod, "_repo_path", str(repo))+ result = _enforce(tool, _payload(tool, pad))++ accounting = result["_meta"]["response_budget"]+ assert required in result+ assert accounting == {+ "limit_chars": DEFAULT_RESPONSE_CHARS,+ "tier": "default",+ "serialized_chars": len(json.dumps(result, separators=(",", ":"), default=str)),+ }+ assert "truncated" not in result+++ ("tool", "required"),+ [+ ("get_context", "targets"),+ ("get_risk", "directive"),+ ("get_change_risk", "classification"),+ ("get_answer", "answer"),+ ("get_overview", "title"),+ ],+)+def test_adversarial_payload_goldens_fit_and_recover_in_one_lookup(+ setup_mcp: str,+ tmp_path: Path,+ monkeypatch: pytest.MonkeyPatch,+ tool: str,+ required: str,+) -> None:+ import repowise.server.mcp_server as mcp_mod++ repo = tmp_path / tool+ (repo / ".repowise").mkdir(parents=True)+ monkeypatch.setattr(mcp_mod, "_repo_path", str(repo))+ result = _enforce(tool, _payload(tool, 15_000))+ size = len(json.dumps(result, separators=(",", ":"), default=str))++ accounting = result["_meta"]["response_budget"]+ assert required in result+ assert size == accounting["serialized_chars"] <= accounting["limit_chars"]+ assert accounting["limit_chars"] == DEFAULT_RESPONSE_CHARS+ assert "enforcement_error" not in accounting+ assert result["truncated"] is True+ refs = result["_meta"]["omitted"]["refs"]+ assert refs+ if tool == "get_risk":+ reductions = result["_meta"].get("reductions", [])+ assert reductions and all(+ row["total"] >= row["emitted"] and row["reason"] == "response_budget"+ for row in reductions+ )+ elif tool == "get_change_risk":+ assert result["prior_fixes_total"] == 3+ assert result["prior_fixes_emitted"] == 0+ assert result["prior_fixes_reduced_reason"] == "response_budget"++ store = OmissionStore(default_store_path(repo))+ try:+ recovered = [store.get(ref) for ref in refs]+ finally:+ store.close()+ assert any(value is not None and f"EVIDENCE_{tool}" in value for value in recovered)+++def test_explicit_include_uses_the_expansion_tier(+ setup_mcp: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ import repowise.server.mcp_server as mcp_mod++ (tmp_path / ".repowise").mkdir()+ monkeypatch.setattr(mcp_mod, "_repo_path", str(tmp_path))+ result = _enforce("get_overview", _payload("get_overview", 8_000), ["content"])+ accounting = result["_meta"]["response_budget"]+ assert accounting["tier"] == "expanded"+ assert accounting["limit_chars"] == EXPANDED_RESPONSE_CHARS+ assert accounting["serialized_chars"] <= EXPANDED_RESPONSE_CHARS+++def test_oversized_protected_answer_is_reduced_and_recoverable(+ setup_mcp: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ import repowise.server.mcp_server as mcp_mod++ (tmp_path / ".repowise").mkdir()+ monkeypatch.setattr(mcp_mod, "_repo_path", str(tmp_path))+ payload = _payload("get_answer", 0)+ payload["answer"] = "PROTECTED_ANSWER_" + "z" * 50_000+ result = _enforce("get_answer", payload)++ accounting = result["_meta"]["response_budget"]+ assert result["answer"].startswith("PROTECTED_ANSWER_")+ assert accounting["serialized_chars"] <= DEFAULT_RESPONSE_CHARS+ assert result["_meta"]["state"]["truncated"] is True+ assert "enforcement_error" not in accounting+ refs = result["_meta"]["omitted"]["refs"]+ store = OmissionStore(default_store_path(tmp_path))+ try:+ assert any("PROTECTED_ANSWER_" in (store.get(ref) or "") for ref in refs)+ finally:+ store.close()+++async def test_middleware_budgets_after_trust_metadata(+ setup_mcp: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ import repowise.server.mcp_server as mcp_mod++ (tmp_path / ".repowise").mkdir()+ monkeypatch.setattr(mcp_mod, "_repo_path", str(tmp_path))++ async def get_risk() -> dict:+ return _payload("get_risk", 15_000)++ result = await tool_middleware(get_risk)()+ assert result["_meta"]["contract_version"] == 1+ accounting = result["_meta"]["response_budget"]+ assert accounting["serialized_chars"] == len(+ json.dumps(result, separators=(",", ":"), default=str)+ )+ assert accounting["serialized_chars"] <= DEFAULT_RESPONSE_CHARS+++async def test_budget_repo_root_follows_workspace_alias(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ from types import SimpleNamespace++ import repowise.server.mcp_server._helpers as helpers++ selected = tmp_path / "selected"++ async def resolve(repo: str | None = None) -> Any:+ assert repo == "other"+ return SimpleNamespace(path=selected)++ monkeypatch.setattr(helpers, "_resolve_repo_context", resolve)++ def call(repo: str | None = None) -> None:+ pass++ signature = inspect.signature(call)+ assert await resolve_response_budget_repo_root(signature, (), {"repo": "other"}) == selected