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.

fix(mcp): keep the projection a caller asked for ahead of the ones they did not (#2270)

Raghav Chamadiya8a4941ab8322
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 f460d4032..d9c1cafc4 100644
--- a/packages/server/src/repowise/server/mcp_server/_budget/budgeter.py
+++ b/packages/server/src/repowise/server/mcp_server/_budget/budgeter.py
@@ -35,8 +35,10 @@ from __future__ import annotations
import json
import logging
+import math
import os
from collections.abc import Sequence
+from dataclasses import dataclass
from typing import Any
from repowise.server.mcp_server._budget.collector import OmissionCollector
@@ -164,6 +166,44 @@ def over_budget(
return response_chars(response) > budget - headroom
+#: A requested collection keeps whichever of these is larger.
+REQUESTED_MIN_ROWS = 3
+REQUESTED_MIN_SHARE = 0.25
+
+
+def entitled_floor(total: int) -> int:
+ """Rows a caller-requested collection keeps before anything else sheds."""
+ if total <= REQUESTED_MIN_ROWS:
+ return total
+ return min(total, max(REQUESTED_MIN_ROWS, math.ceil(total * REQUESTED_MIN_SHARE)))
+
+
+def shed_stem(key: str) -> str:
+ """The response path a shed-order key names, with the ``[]`` form removed."""
+ return key[:-2] if key.endswith("[]") else key
+
+
+def _rows_to_keep(rows: Any, requested: bool) -> int:
+ """Tail-shed floor for one collection: its entitlement, or one row."""
+ if not requested or not isinstance(rows, (list, dict)):
+ return 1
+ return entitled_floor(len(rows))
+
+
+@dataclass(frozen=True)
+class _ShedLimits:
+ """The knobs every key in one :func:`fit_to_budget` pass shares."""
+
+ headroom: int
+ char_budget: int | None
+ record_counts: bool
+
+ def exceeded(self, response: dict[str, Any]) -> bool:
+ return over_budget(
+ response, headroom=self.headroom, char_budget=self.char_budget
+ )
+
+
def fit_to_budget(
response: dict[str, Any],
order: Sequence[str],
@@ -172,6 +212,7 @@ def fit_to_budget(
headroom: int = FIT_HEADROOM_CHARS,
char_budget: int | None = None,
record_counts: bool = False,
+ entitled: frozenset[str] | None = None,
) -> dict[str, Any]:
"""Shed whole blocks named by *order* until *response* fits the budget.
@@ -181,12 +222,18 @@ def fit_to_budget(
first. Shedding stops the moment the response fits, so an under-budget
response — the common case — is untouched.
+ *entitled* names stems the caller asked for; their ``[]`` passes stop at
+ :func:`entitled_floor` instead of one row. The order still decides when a
+ block is reached, and the ceiling still wins.
+
Drops go to *collector* as expandable ``[repowise#<ref>]`` markers and set
``truncated``. Call before the caller's :meth:`OmissionCollector.attach`,
which is what ``headroom`` reserves for.
"""
+ limits = _ShedLimits(headroom, char_budget, record_counts)
+ requested = entitled or frozenset()
for key in order:
- if not over_budget(response, headroom=headroom, char_budget=char_budget):
+ if not limits.exceeded(response):
break
container, _, leaf = key.rpartition(".")
target: Any = response
@@ -195,16 +242,8 @@ def fit_to_budget(
if not isinstance(target, dict):
continue
if leaf.endswith("[]"):
- _shed_tail(
- response,
- target,
- leaf[:-2],
- key[:-2],
- collector,
- headroom,
- char_budget,
- record_counts,
- )
+ keep = _rows_to_keep(target.get(leaf[:-2]), shed_stem(key) in requested)
+ _shed_tail(response, target, leaf[:-2], key[:-2], collector, limits, keep)
elif target.get(leaf):
value = target.pop(leaf)
collector.add(key, value)
@@ -220,19 +259,16 @@ def _shed_tail(
leaf: str,
label: str,
collector: OmissionCollector,
- headroom: int,
- char_budget: int | None,
- record_counts: bool,
+ limits: _ShedLimits,
+ keep: int = 1,
) -> None:
- """Drop ranked rows from the tail of ``container[leaf]`` until it fits."""
+ """Drop ranked rows from the tail of ``container[leaf]`` down to *keep*."""
rows = container.get(leaf)
if not isinstance(rows, (list, dict)):
return
total = len(rows)
dropped: list[Any] = []
- while len(rows) > 1 and over_budget(
- response, headroom=headroom, char_budget=char_budget
- ):
+ while len(rows) > keep and limits.exceeded(response):
if isinstance(rows, list):
dropped.append(rows.pop())
else:
@@ -240,7 +276,7 @@ def _shed_tail(
dropped.append({name: rows.pop(name)})
if dropped:
collector.add(label, list(reversed(dropped)))
- if record_counts:
+ if limits.record_counts:
prior_reason = container.get(f"{leaf}_reduced_reason")
collection_total = max(
total, int(container.get(f"{leaf}_total") or 0)
@@ -280,21 +316,24 @@ def _record_reduction(
reductions = response.setdefault("_meta", {}).setdefault("reductions", [])
- def visit(node: Any, node_path: str) -> None:
+ def visit(node: Any, node_path: str, parent: dict[str, Any], name: str) -> None:
if isinstance(node, list):
+ # An earlier tail-shed may already have trimmed this list and left
+ # the population beside it. Reporting len() here would count only
+ # what the trim left, not what the caller lost overall.
reductions.append(
{
"field": node_path,
- "total": len(node),
+ "total": max(len(node), int(parent.get(f"{name}_total") or 0)),
"emitted": 0,
"reason": "response_budget",
}
)
elif isinstance(node, dict):
- for name, child in node.items():
- visit(child, f"{node_path}.{name}")
+ for child_name, child in node.items():
+ visit(child, f"{node_path}.{child_name}", node, child_name)
- visit(value, path)
+ visit(value, path, container, field)
def _with_budget_reason(prior_reason: Any) -> str:
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 dfec9c0d8..b8447e519 100644
--- a/packages/server/src/repowise/server/mcp_server/_budget/contracts.py
+++ b/packages/server/src/repowise/server/mcp_server/_budget/contracts.py
@@ -18,6 +18,7 @@ from repowise.server.mcp_server._budget.budgeter import (
effective_char_budget,
fit_to_budget,
response_chars,
+ shed_stem,
truncate_to_budget,
)
from repowise.server.mcp_server._budget.collector import OmissionCollector
@@ -45,6 +46,16 @@ class ResponseBudgetContract:
#: uncounted rather than proven absent, so the count is a lower bound.
#: A ``<field>_total`` name here is also read as a reduction total.
floor_fields: tuple[str, ...] = ()
+ #: ``(request token, shed-order keys)``. The token is an ``include`` value
+ #: or an argument whose presence is itself the request. Keys named here
+ #: shed last and trim to :func:`entitled_floor`; the ceiling still wins, so
+ #: this is priority, not immunity. Declaring nothing keeps a tool's
+ #: existing behaviour.
+ requested_projections: tuple[tuple[str, tuple[str, ...]], ...] = ()
+
+
+#: Arguments whose presence asks for the projection that answers them.
+_IMPLICIT_REQUEST_ARGUMENTS = ("query", "id", "reference", "changed_files", "targets")
#: What a tool gets when it declares no priority of its own. An empty shed
@@ -77,6 +88,22 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {
"impact_surface_total",
"co_change_partners_total",
),
+ requested_projections=(
+ (
+ "changed_files",
+ (
+ "directive.test_recommendations[]",
+ "directive.tests_to_run[]",
+ "directive.may_break[]",
+ "pr_blast_radius",
+ "pr_blast_radius.guarding_tests",
+ ),
+ ),
+ # targets is required, so it is always asked for. Without this the
+ # deferred PR blocks jump ahead of it and the rows the caller
+ # named become the first thing trimmed.
+ ("targets", ("targets[]",)),
+ ),
),
"get_change_risk": ResponseBudgetContract(
"blocks",
@@ -113,6 +140,7 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {
"retrieval[]",
"retrieval",
"code_rationale",
+ "quotes[]",
"quotes",
"symbol_bodies[]",
"symbol_bodies",
@@ -125,6 +153,20 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {
),
expansion_argument="include",
protected=("answer", "confidence", "citations", "next_action_hint", "degraded"),
+ requested_projections=(
+ (
+ "evidence",
+ (
+ "retrieval[]",
+ "retrieval",
+ "symbol_bodies[]",
+ "symbol_bodies",
+ "quotes[]",
+ "quotes",
+ "code_rationale",
+ ),
+ ),
+ ),
),
# Whole-block drops served 0 of 50 pages, 0 of 12 episodes and 0 of 58
# mined rationale comments across the two modes. Trimming runs to
@@ -162,6 +204,21 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {
"candidates",
"origin_story",
),
+ requested_projections=(
+ (
+ "query",
+ (
+ "decisions[]",
+ "candidates[]",
+ "history[]",
+ "related_documentation[]",
+ "code_rationale[]",
+ "episodes[]",
+ ),
+ ),
+ ("id", ("decisions[]",)),
+ ("reference", ("decisions[]",)),
+ ),
expansion_argument=None,
protected=(
"mode",
@@ -188,6 +245,9 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {
"knowledge_map",
"key_decisions",
"outline_hint",
+ # Trim the sections before dropping the block: shed as one unit it
+ # served 0 of 40 while 73% of the budget went unspent.
+ "outline.sections[]",
"outline",
"tool_surface",
"repos[]",
@@ -195,6 +255,15 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {
"content_md",
),
protected=("title", "architecture", "entry_points"),
+ requested_projections=(
+ ("outline", ("outline.sections[]", "outline", "outline_hint")),
+ ("tour", ("guided_tour", "guided_tour_hint", "reading_order",
+ "reading_order_hint")),
+ ("decisions", ("key_decisions",)),
+ ("graph", ("community_summary",)),
+ ("ownership", ("knowledge_map",)),
+ ("content", ("content_md",)),
+ ),
),
"get_health": ResponseBudgetContract(
"blocks",
@@ -267,7 +336,7 @@ _CONTRACTS: dict[str, ResponseBudgetContract] = {
# metadata that followed added roughly 2.6k.
"search_codebase": ResponseBudgetContract(
"blocks",
- ("candidates", "results[]"),
+ ("candidates[]", "candidates", "results[]"),
expansion_argument=None,
protected=("results", "mode", "exact_match"),
),
@@ -378,6 +447,63 @@ def _call_uses_expansion(
return bool(bound.arguments.get(contract.expansion_argument))
+def _include_tokens(value: Any) -> set[str]:
+ """Normalise an ``include`` argument to a set of tokens.
+
+ This layer sits outside the failure shield, so anything the caller can
+ send has to come back as a set rather than an exception.
+ """
+ if isinstance(value, str):
+ return {value}
+ if isinstance(value, (list, tuple, set, frozenset)):
+ return {str(token) for token in value}
+ return set()
+
+
+def _requested_shed_keys(
+ contract: ResponseBudgetContract,
+ signature: inspect.Signature,
+ args: tuple[Any, ...],
+ kwargs: dict[str, Any],
+) -> frozenset[str]:
+ """Shed-order stems this particular call asked for."""
+ if not contract.requested_projections:
+ return frozenset()
+ try:
+ bound = dict(signature.bind_partial(*args, **kwargs).arguments)
+ except TypeError:
+ bound = dict(kwargs)
+
+ asked = _include_tokens(bound.get("include"))
+ asked.update(name for name in _IMPLICIT_REQUEST_ARGUMENTS if bound.get(name))
+
+ keys: set[str] = set()
+ for token, paths in contract.requested_projections:
+ if token in asked:
+ keys.update(shed_stem(path) for path in paths)
+ return frozenset(keys)
+
+
+def _prioritised_shed_order(
+ order: tuple[str, ...], requested: frozenset[str]
+) -> tuple[str, ...]:
+ """Move what the caller asked for to the back of the shed order.
+
+ Within that tail every trimmable key runs before any whole-block drop, so
+ two requested blocks cannot end with one trimmed to its floor and the
+ other dropped entirely. Relative order is otherwise preserved.
+ """
+ if not requested:
+ return order
+ deferred = tuple(key for key in order if shed_stem(key) in requested)
+ if not deferred:
+ return order
+ kept = tuple(key for key in order if shed_stem(key) not in requested)
+ trimmable = tuple(key for key in deferred if key.endswith("[]"))
+ whole = tuple(key for key in deferred if not key.endswith("[]"))
+ return kept + trimmable + whole
+
+
def _stamp_accounting(result: dict[str, Any], *, limit: int, tier: str) -> None:
meta = result.setdefault("_meta", {})
budget = meta.setdefault("response_budget", {})
@@ -487,6 +613,7 @@ def _emergency_fit(
contract: ResponseBudgetContract,
collector: OmissionCollector,
limit: int,
+ requested: frozenset[str] = frozenset(),
) -> None:
"""Bound an unexpectedly huge protected core without a false fit claim."""
protected = {*contract.protected, "_meta"}
@@ -497,7 +624,12 @@ def _emergency_fit(
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):
+ # Biggest first, but never a requested block while an unrequested one is
+ # still there to drop.
+ def order(item: str) -> tuple[bool, int]:
+ return (item in requested, -response_chars(result[item]))
+
+ for key in sorted(removable, key=order):
if response_chars(result) <= limit:
return
value = result.pop(key)
@@ -617,6 +749,7 @@ def enforce_response_budget(
collector = OmissionCollector(tool, repo_root=repo_root)
headroom = min(_FINAL_HEADROOM_CHARS, max(100, limit // 4))
working_limit = max(1, limit - headroom)
+ requested = _requested_shed_keys(contract, signature, args, kwargs)
if contract.strategy == "targets":
truncate_to_budget(
result,
@@ -627,18 +760,19 @@ def enforce_response_budget(
else:
fit_to_budget(
result,
- contract.shed_order,
+ _prioritised_shed_order(contract.shed_order, requested),
collector,
char_budget=working_limit,
headroom=0,
record_counts=True,
+ entitled=requested,
)
run_post_shed(tool, result, collector)
collector.attach(result)
if response_chars(result) > limit:
emergency = OmissionCollector(tool, repo_root=repo_root)
- _emergency_fit(result, contract, emergency, working_limit)
+ _emergency_fit(result, contract, emergency, working_limit, requested)
emergency.attach(result)
run_post_enforce(tool, result)
diff --git a/tests/unit/server/mcp/test_requested_projection_priority.py b/tests/unit/server/mcp/test_requested_projection_priority.py
new file mode 100644
index 000000000..e5640027b
--- /dev/null
+++ b/tests/unit/server/mcp/test_requested_projection_priority.py
@@ -0,0 +1,228 @@
+"""What the caller asked for sheds last, and trims instead of vanishing."""
+
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+import pytest
+
+from repowise.server.mcp_server._budget import enforce_response_budget
+from repowise.server.mcp_server._budget.budgeter import entitled_floor, shed_stem
+from repowise.server.mcp_server._budget.contracts import (
+ _CONTRACTS,
+ ResponseBudgetContract,
+ _prioritised_shed_order,
+ _requested_shed_keys,
+)
+
+
+def _overview_signature() -> inspect.Signature:
+ def get_overview(repo: str | None = None, include: list[str] | None = None): ...
+
+ return inspect.signature(get_overview)
+
+
+def _overview_payload(sections: int = 40) -> dict[str, Any]:
+ return {
+ "title": "Repository Overview",
+ "architecture": {"layers": []},
+ "entry_points": [],
+ "outline": {
+ "sections": [
+ {"title": f"section {i}", "body": "x" * 900} for i in range(sections)
+ ]
+ },
+ "content_md": "y" * 4000,
+ "key_modules": [{"name": f"module {i}"} for i in range(30)],
+ "tool_surface": {
+ "tools": [{"name": f"tool {i}", "description": "z" * 200} for i in range(11)]
+ },
+ "_meta": {"contract_version": 1},
+ }
+
+
+def _enforce(tool: str, payload: dict[str, Any], **kwargs: Any) -> dict[str, Any]:
+ return enforce_response_budget(
+ tool,
+ payload,
+ signature=_overview_signature(),
+ args=(),
+ kwargs=kwargs,
+ repo_root=None,
+ )
+
+
+ ("total", "expected"),
+ [(0, 0), (1, 1), (3, 3), (4, 3), (12, 3), (40, 10), (400, 100)],
+)
+def test_entitled_floor_never_exceeds_population(total: int, expected: int) -> None:
+ assert entitled_floor(total) == expected
+
+
+def test_requested_outline_survives_and_spends_the_budget() -> None:
+ result = _enforce("get_overview", _overview_payload(), include=["outline"])
+
+ sections = result["outline"]["sections"]
+ budget = result["_meta"]["response_budget"]
+ assert len(sections) >= entitled_floor(40)
+ # The regression was 0 of 40 served while 73% of the budget went unspent.
+ assert budget["serialized_chars"] > budget["limit_chars"] * 0.75
+
+
+def test_asking_for_a_block_keeps_more_of_it_than_not_asking() -> None:
+ """Entitlement is not a licence to keep everything on every call."""
+ asked = _enforce("get_overview", _overview_payload(), include=["outline"])
+ unasked = _enforce("get_overview", _overview_payload())
+
+ kept = len(asked["outline"]["sections"])
+ incidental = len((unasked.get("outline") or {}).get("sections", []))
+ assert kept > incidental
+ assert unasked["truncated"] is True
+
+
+def test_requested_block_outlives_unrequested_ones() -> None:
+ result = _enforce("get_overview", _overview_payload(), include=["outline"])
+
+ assert result["outline"]["sections"]
+ assert "community_summary" not in result
+
+
+def test_trimmed_requested_collection_keeps_recoverable_counts() -> None:
+ result = _enforce("get_overview", _overview_payload(), include=["outline"])
+ outline = result["outline"]
+
+ if outline.get("sections_truncated"):
+ assert outline["sections_total"] == 40
+ assert outline["sections_emitted"] == len(outline["sections"])
+ assert outline["sections_omitted"] == 40 - len(outline["sections"])
+ assert result["_meta"]["omitted"]["refs"]
+
+
+def test_response_still_obeys_the_hard_ceiling() -> None:
+ """A requested projection may be trimmed; it may not burst the ceiling."""
+ result = _enforce("get_overview", _overview_payload(sections=4000), include=["outline"])
+
+ budget = result["_meta"]["response_budget"]
+ assert budget["serialized_chars"] <= budget["limit_chars"]
+
+
+def test_declaring_nothing_leaves_the_shed_order_alone() -> None:
+ contract = ResponseBudgetContract("blocks", ("a", "b[]", "c"))
+ requested = _requested_shed_keys(
+ contract, _overview_signature(), (), {"include": ["a"]}
+ )
+
+ assert requested == frozenset()
+ assert _prioritised_shed_order(contract.shed_order, requested) == ("a", "b[]", "c")
+
+
+def test_priority_defers_requested_keys_and_keeps_relative_order() -> None:
+ order = ("a", "b[]", "c", "d")
+
+ assert _prioritised_shed_order(order, frozenset({"b", "c"})) == ("a", "d", "b[]", "c")
+
+
+def test_every_requested_trim_runs_before_any_requested_whole_drop() -> None:
+ """Two requested blocks must not end with one trimmed and one deleted."""
+ order = ("x", "tour", "outline.sections[]", "outline")
+
+ assert _prioritised_shed_order(order, frozenset({"tour", "outline.sections", "outline"})) == (
+ "x",
+ "outline.sections[]",
+ "tour",
+ "outline",
+ )
+
+
+def test_a_non_iterable_include_does_not_raise() -> None:
+ """This layer sits outside the failure shield."""
+ contract = ResponseBudgetContract(
+ "blocks", ("a[]",), requested_projections=(("z", ("a[]",)),)
+ )
+
+ assert _requested_shed_keys(
+ contract, _overview_signature(), (), {"include": 5}
+ ) == frozenset()
+
+
+def test_risk_targets_are_not_trimmed_ahead_of_pr_blocks() -> None:
+ """targets is required, so PR mode must not shed it first."""
+ def get_risk(
+ targets: list[str],
+ repo: str | None = None,
+ changed_files: list[str] | None = None,
+ include: list[str] | None = None,
+ ): ...
+
+ requested = _requested_shed_keys(
+ _CONTRACTS["get_risk"],
+ inspect.signature(get_risk),
+ (),
+ {"targets": ["a.py"], "changed_files": ["a.py"]},
+ )
+ order = _prioritised_shed_order(_CONTRACTS["get_risk"].shed_order, requested)
+
+ # Ambient repo-wide context goes before anything the caller named, and
+ # target rows keep their entitlement rather than collapsing to one.
+ assert order.index("global_hotspots") < order.index("targets[]")
+ assert "targets" in requested
+
+
+def test_a_trimmed_then_dropped_block_reports_the_whole_population() -> None:
+ """outline.sections[] trims, then outline is dropped: totals must survive."""
+ payload = _overview_payload()
+ outline = payload["outline"]
+ outline["sections"] = outline["sections"][:10]
+ outline["sections_total"] = 40
+ outline["sections_emitted"] = 10
+
+ result = enforce_response_budget(
+ "get_overview",
+ {**payload, "content_md": "y" * 40_000},
+ signature=_overview_signature(),
+ args=(),
+ kwargs={},
+ repo_root=None,
+ )
+
+ rows = [
+ row
+ for row in result["_meta"].get("reductions", [])
+ if row["field"] == "outline.sections"
+ ]
+ if rows:
+ assert rows[0]["total"] == 40
+
+
+def test_query_mode_counts_as_a_request() -> None:
+ def get_why(query: str | None = None, targets: list[str] | None = None): ...
+
+ requested = _requested_shed_keys(
+ _CONTRACTS["get_why"], inspect.signature(get_why), (), {"query": "why JWT?"}
+ )
+
+ assert "decisions" in requested
+ assert "episodes" in requested
+
+
+def test_no_query_asks_for_nothing() -> None:
+ def get_why(query: str | None = None, targets: list[str] | None = None): ...
+
+ requested = _requested_shed_keys(
+ _CONTRACTS["get_why"], inspect.signature(get_why), (), {"targets": ["a.py"]}
+ )
+
+ assert requested == frozenset()
+
+
[email protected]("tool", sorted(_CONTRACTS))
+def test_declared_projections_name_real_shed_order_keys(tool: str) -> None:
+ """A projection mapping a key the shed order lacks silently does nothing."""
+ contract = _CONTRACTS[tool]
+ stems = {shed_stem(key) for key in contract.shed_order}
+
+ for token, paths in contract.requested_projections:
+ for path in paths:
+ assert shed_stem(path) in stems, f"{tool}: {token} -> {path}"