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): stop returning payload the caller already has (#1426)

Raghav Chamadiyae9ec97b07010
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index 5124ea512..571040157 100644
--- a/docs/reference/CLI_REFERENCE.md
+++ b/docs/reference/CLI_REFERENCE.md
@@ -497,11 +497,14 @@ call.
```bash
repowise context src/api/routes.py src/api/auth.py
repowise context src/api/routes.py::login --include callers --include metrics
-repowise context src/api/routes.py --full # includes the skeleton source
+repowise context src/api/routes.py --include skeleton # + the file's source
```
-The skeleton's *text* is the bulk of the underlying payload, so the default
-reports its size and coverage and `--full` carries the source.
+**No source bytes by default.** A card is relationships and risk signals:
+title, summary, signatures with line numbers, hotspot, fix history. Pass
+`--include skeleton` for the whole file body-elided and line-verified in one
+call, or just read the file. `--full` returns the raw tool dict, which carries
+a skeleton only when one was asked for.
---
diff --git a/packages/cli/src/repowise/cli/commands/context_cmd.py b/packages/cli/src/repowise/cli/commands/context_cmd.py
index 4fda37ee0..e5ca151b6 100644
--- a/packages/cli/src/repowise/cli/commands/context_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/context_cmd.py
@@ -41,7 +41,7 @@ _REPLACED_KEYS = frozenset(
# Folded into flatter keys.
"architectural_layer",
"freshness",
- # Replaced by its shape, without its ~10K-char text.
+ # Placed by hand below, whole: opt-in, so it was asked for.
"skeleton",
# A breadcrumb to the wiki page the card came from, not a signal.
"parent_page",
@@ -103,18 +103,13 @@ def _project_one(card: dict) -> dict:
out[key] = value
skeleton = card.get("skeleton") or {}
if skeleton:
- # The skeleton *text* is the bulk of get_context's payload — 10K chars
- # for one file — and it is source a caller can also get from `symbol`
- # or a plain Read. The card keeps its shape and size so a caller can
- # decide whether to pay for it; --full carries the text.
- out["skeleton"] = {
- "mode": skeleton.get("mode", ""),
- "tokens": skeleton.get("tokens"),
- "full_tokens": skeleton.get("full_tokens"),
- "pct_of_full": skeleton.get("pct_of_full"),
- "verified": skeleton.get("verified"),
- "bodies_kept": skeleton.get("bodies_kept") or [],
- }
+ # The skeleton is opt-in on the tool now (``--include skeleton``), so a
+ # card that carries one carries it because this caller asked by name.
+ # Trimming its ``text`` away here would make the flag inert — the
+ # failure mode the ``--include`` passthrough above exists to avoid — so
+ # the block passes through whole. It is still summarised rather than
+ # printed on the table path.
+ out["skeleton"] = skeleton
return out
@@ -127,16 +122,13 @@ def project(payload: dict, targets: tuple[str, ...]) -> dict:
kept target, type, docs.title -> title,
docs.summary -> summary,
architectural_layer.name -> layer,
- freshness.is_stale -> stale, the skeleton's
- shape without its ``text``, and **every other
+ freshness.is_stale -> stale, and **every other
key the card carries** — hotspot, fix_history,
- episodes, and each ``--include`` block under
- its own name
- dropped skeleton.text (~10K chars per file, the bulk
- of the payload), skeleton.opt_out_hint /
- auto, parent_page,
- freshness.confidence_score, ``_meta`` minus
- its freshness keys
+ episodes, the skeleton when ``--include
+ skeleton`` asked for one, and each other
+ ``--include`` block under its own name
+ dropped parent_page, freshness.confidence_score,
+ ``_meta`` minus its freshness keys
================== ===========================================
A target the tool could not resolve gets a card carrying only ``error``,
@@ -199,8 +191,8 @@ def context_command(
TARGETS are file paths, module paths, or "path/to/file.py::Symbol" ids.
Batch them in one call. Relationships and risk signals, not source bytes:
- pass --full for the verified skeleton, or use 'repowise symbol' for one
- body.
+ pass --include skeleton for the whole file body-elided and line-verified,
+ or just read the file.
"""
fmt = _ta.resolve_format_for(fmt, full)
repo_path = _ta.resolve_indexed_repo(
@@ -286,11 +278,14 @@ def _render(projected: dict) -> None:
table.add_row("Signals", ", ".join(signals))
skeleton = card.get("skeleton") or {}
if skeleton:
+ # Summarised, never printed: the text is the reason the caller
+ # passed --include skeleton, and a terminal table is not where a
+ # few thousand lines of source belong. --format json carries it.
table.add_row(
"Skeleton",
f"{skeleton.get('mode', '?')}, {skeleton.get('tokens', '?')} of "
f"{skeleton.get('full_tokens', '?')} tokens "
- f"({skeleton.get('pct_of_full', '?')}% of full) — pass --full for the text",
+ f"({skeleton.get('pct_of_full', '?')}% of full) — --format json for the text",
)
if card.get("decision_records"):
table.add_row(
diff --git a/packages/core/src/repowise/core/generation/editor_files/tool_table.py b/packages/core/src/repowise/core/generation/editor_files/tool_table.py
index 3f57b3a59..49c6242bf 100644
--- a/packages/core/src/repowise/core/generation/editor_files/tool_table.py
+++ b/packages/core/src/repowise/core/generation/editor_files/tool_table.py
@@ -40,9 +40,9 @@ TOOL_TABLE_ROWS: dict[str, tuple[str, str]] = {
),
"get_context": (
"get_context(targets=[...])",
- "Triage card for files/modules/symbols, serving a `verified` skeleton for "
- 'file targets. Batch targets; `include=["callers"|"callees"|"decisions"|'
- '"metrics"]` for depth.',
+ "Triage card for files/modules/symbols: docs, signatures, hotspot, fix "
+ 'history. No source bytes — `include=["skeleton"]` for the whole file '
+ 'verified, `["callers"|"decisions"]` for depth. Batch targets.',
),
"get_symbol": (
"get_symbol(id)",
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 a4325c579..6f6e0438b 100644
--- a/packages/server/src/repowise/server/mcp_server/_budget/budgeter.py
+++ b/packages/server/src/repowise/server/mcp_server/_budget/budgeter.py
@@ -215,6 +215,15 @@ def truncate_to_budget(
"dropped_symbol_counts": {k: len(v) for k, v in result["dropped_symbols"].items()},
},
)
+ else:
+ # Nothing was dropped, so say nothing. ``truncated: false`` +
+ # ``dropped_targets: []`` + ``dropped_symbols: {}`` is 60 characters of
+ # "nothing happened" on every untruncated response — and every response
+ # is untruncated in the common case. Absent reads the same as empty to
+ # a ``.get()``, which is how both projections already test them.
+ for key in ("truncated", "dropped_targets", "dropped_symbols"):
+ if not result.get(key):
+ result.pop(key, None)
return result
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 1bd2e96c1..efffe9ab9 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
@@ -145,6 +145,7 @@ from repowise.server.mcp_server.tool_answer.episodes import (
attach_episode as _attach_episode,
)
from repowise.server.mcp_server.tool_answer.retrieval import (
+ _CANDIDATE_LIMIT,
_apply_domain_penalty,
_attach_page_excerpts,
_candidate_justification,
@@ -401,7 +402,10 @@ def _build_best_guesses(hits: list[dict]) -> list[dict]:
"file": h.get("target_path"),
"why_relevant": _candidate_justification(h),
"score": round(h.get("score", 0.0), 3),
- "domain_penalty": h.get("_domain_penalty"),
+ # Absent rather than null. It was `null` in all six wire samples
+ # measured 2026-08-11 — a penalty applies to a minority of hits, so
+ # the common row paid 22 characters to say nothing happened.
+ **({"domain_penalty": h["_domain_penalty"]} if h.get("_domain_penalty") else {}),
**({"excerpt": h["excerpt"]} if h.get("excerpt") else {}),
}
for h in hits[:_GATED_RETURN_HITS]
@@ -409,6 +413,67 @@ def _build_best_guesses(hits: list[dict]) -> list[dict]:
]
+def _trim_served_payload(payload: dict) -> dict:
+ """Every size cut that runs on the way OUT, on both the fresh and cache paths.
+
+ Serve-time rather than build-time, and that is the whole point. A cut
+ applied where the payload is assembled reaches only fresh answers: a cache
+ row written by an older build keeps the old shape until
+ ``_ANSWER_SCHEMA_VERSION`` moves, and bumping that invalidates every user's
+ answer cache — re-synthesis, i.e. real provider spend — to change the size
+ of a block. Measured: after capping ``candidates`` at build time only, a
+ re-measured ``get_answer`` came back byte-identical, because the tree's
+ cache answered. Trimming on the way out fixes old and new rows alike and
+ costs nobody a re-synthesis.
+
+ Anything that only REMOVES redundancy belongs here. Anything that changes
+ what an answer says does not, and still owes a schema bump.
+ """
+ _cap_candidates(payload)
+ _drop_duplicated_guess_excerpts(payload)
+ return payload
+
+
+def _cap_candidates(payload: dict) -> dict:
+ """Hold ``candidates`` to :data:`_CANDIDATE_LIMIT` rows on the way out."""
+ candidates = payload.get("candidates")
+ if isinstance(candidates, list) and len(candidates) > _CANDIDATE_LIMIT:
+ payload["candidates"] = candidates[:_CANDIDATE_LIMIT]
+ return payload
+
+
+def _drop_duplicated_guess_excerpts(payload: dict) -> dict:
+ """Drop ``best_guesses[].excerpt`` where ``retrieval[]`` already carries it.
+
+ Both blocks slice the same 1,500-character page excerpt for the same file,
+ and when both are present the guess copy is byte-for-byte redundant —
+ measured at 4,714 characters, 21.3% of one low-confidence payload, 3 of 3
+ guesses duplicated.
+
+ **Conditional, and the condition matters.** ``retrieval`` is
+ confidence-gated and shrinks to nothing as the prose gets more
+ trustworthy; the legacy abstain path ships ``retrieval: []`` outright. On
+ those responses the guess excerpt is the only content in the payload, not a
+ duplicate of anything, and a sample measured here carried 4,667 characters
+ of it. So the drop is keyed on the duplicate actually being present, which
+ makes it lossless rather than merely cheap — and keeps every ``excerpt``
+ mentioned by ``note`` / ``next_action_hint`` on the paths that mention it.
+ """
+ guesses = payload.get("best_guesses")
+ if not guesses:
+ return payload
+ # Substring, not equality: the two blocks cut their slabs independently and
+ # the retrieval one is the longer of the two where they differ.
+ carried = [r["excerpt"] for r in (payload.get("retrieval") or []) if r.get("excerpt")]
+ if not carried:
+ return payload
+ for guess in guesses:
+ excerpt = guess.get("excerpt")
+ if excerpt and any(excerpt in c for c in carried):
+ del guess["excerpt"]
+ return payload
+
+
def _json_default(obj):
"""Serialize the non-JSON types retrieval hits carry (``_sources`` sets).
@@ -890,6 +955,7 @@ async def get_answer(
targets=[p for p in cached_paths if isinstance(p, str) and p],
)
_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
@@ -1895,6 +1961,10 @@ async def get_answer(
if degraded := _degraded_legs(_retrieval_legs()):
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. ``cache_payload`` is a shallow
# copy taken before this point, so the episode reaches the caller and never
# the cache row — which is why adding it needs no _ANSWER_SCHEMA_VERSION
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py b/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py
index a8115aaf8..396f445a4 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/retrieval.py
@@ -34,10 +34,22 @@ from repowise.server.mcp_server.tool_answer.config import (
_log = logging.getLogger("repowise.mcp.answer")
-# How many files ``candidates`` names. Twenty path lines cost roughly 800
-# characters against the ~10k a get_answer response already spends, so the
-# block makes the tool *more* token-efficient per candidate offered, not less.
-_CANDIDATE_LIMIT = 20
+# How many files ``candidates`` names.
+#
+# Was 20, on the estimate that "twenty path lines cost roughly 800 characters
+# against the ~10k a get_answer response already spends". Measured on the wire
+# 2026-08-11 the block is **3,107-3,279 characters, up to 39.9% of a
+# get_answer payload** — four times the estimate, because ``defines`` and the
+# paths themselves are both longer than a bare path line. That estimate was
+# also made before ``defines`` existed.
+#
+# Five, not zero. Rows 6-20 appear in no other block, but nor are rows 1-5
+# redundant: on the repowise samples ``candidates`` is the only block naming
+# files outside the top-two ``citations``, and dropping it whole (which the
+# CLI projection does) pushes the agent into a Grep that costs more than the
+# rows saved. The head keeps the ``defines`` budget, so the navigational value
+# per character goes up.
+_CANDIDATE_LIMIT = 5
def serialize_candidates(hits: list[dict], *, limit: int = _CANDIDATE_LIMIT) -> list[dict]:
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 b8bed5d39..b17e30e04 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
@@ -2,10 +2,12 @@
Workhorse for "what is this and what touches it" questions. Returns a triage
card by default (title, summary, signatures, hotspot bit, top callers, pointers
-to risk / why / symbol). NOT a source-body tool — for raw bytes call
-``get_symbol("path::Name")`` instead. The split keeps the cached prompt prefix
-small on multi-turn agent sessions: ``get_context`` stays under ~2k tokens for
-common targets, while ``get_symbol`` returns bounded bytes for one symbol.
+to risk / why / symbol). **NOT a source-body tool.** For source, ask for it in
+one call — ``include=["skeleton"]`` returns the whole file body-elided and
+line-verified — or just Read the file. Reaching for ``get_symbol`` once per
+signature in the card is the expensive path and the card does not recommend it.
+The split keeps the cached prompt prefix small on multi-turn agent sessions:
+``get_context`` stays under ~2k tokens for common targets.
Optional ``include`` parameter widens the response:
- include=["full_doc"] → full wiki markdown content
@@ -55,18 +57,16 @@ async def get_context(
) -> dict:
"""Triage card for files / modules / symbols — relationships, not source bytes.
- Returns title, summary, signatures, hotspot bit, decision_record titles,
- and symbol_ids to pipe into get_symbol (cheaper than Read for bodies).
- fix_history appears only on files with counted bug fixes (count, age,
- bug_magnet); hotspot is churn. Either one is a cue to call get_risk.
- episodes counts the dated records bound to a target — what happened here
- and why — and appears only when there is at least one; get_why serves the
- bodies. A symbol target is counted as its file, and a module aggregates
- everything beneath it.
- Batch targets in one call. File targets above ~80 lines default to a
- skeleton (every signature + top-PageRank bodies, with a verified flag —
- a fraction of Read cost); ``mostly_full`` marks files where a direct
- Read costs little more.
+ Returns title, summary, signatures with line numbers, hotspot bit, and
+ decision_record titles. fix_history appears only on files with counted bug
+ fixes (count, age, bug_magnet); hotspot is churn. Either one is a cue to
+ call get_risk. episodes counts the dated records bound to a target — what
+ happened here and why — and appears only when there is at least one;
+ get_why serves the bodies. A symbol target is counted as its file, and a
+ module aggregates everything beneath it.
+ Batch targets in one call. No source bytes by default: pass
+ include=["skeleton"] for the whole file body-elided and line-verified in
+ ONE call, or Read it. Do not call get_symbol per signature.
Args:
targets: file paths, module paths, or "path::Symbol" ids.
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py b/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
index 3bbaeb254..83db341db 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
@@ -50,13 +50,27 @@ from repowise.server.mcp_server.tool_context.kg import (
)
from repowise.server.mcp_server.tool_risk.assessment import fix_annotation
-# Skeleton-by-default threshold for file targets. Measured on this repo: a
-# 1,400-line file's default card costs ~2.5k tokens for 16 bare signatures,
-# while the smart skeleton costs ~1.7k and carries every signature plus
-# docstrings and the highest-PageRank bodies — strictly better per token.
-# Small files skeletonize poorly (pct_of_full approaches a plain Read), so
-# the card remains the default below this line count.
-_SKELETON_AUTO_MIN_LINES = 80
+# Skeleton-by-default is GONE; ``include=["skeleton"]`` still serves it in full.
+#
+# It was introduced on the claim that "a 1,400-line file's default card costs
+# ~2.5k tokens for 16 bare signatures, while the smart skeleton costs ~1.7k" —
+# strictly better per token. Re-measured 2026-08-11 on pinned Textualize/rich,
+# whole serialised cards in characters, auto-upgrade suppressed for the
+# comparison:
+#
+# target auto card symbol-list card skeleton text alone
+# rich/ansi.py 6,585 2,171 5,295
+# rich/text.py 13,365 8,562 12,247
+# rich/color.py 8,591 4,818 7,405
+#
+# The symbol list is 1,321 chars on ansi.py where the skeleton text is 5,295.
+# The original claim is inverted on this corpus, and the auto card was 73-91%
+# source text on every sample — text the agent can Read for ~1/5 the marginal
+# cost of a mid-session tool result, which is what the block's own
+# ``mostly_full`` note ("a direct Read costs little more") was already saying
+# at the agent's expense. So the default card is the symbol list again and the
+# skeleton is opt-in. If you restore an auto-upgrade, re-run the measurement
+# first: the numbers above are the bar.
def _synthesize_structural_summary(file_path: str, classes: list[str], functions: list[str]) -> str:
@@ -364,7 +378,6 @@ async def _resolve_one_target(
}
want_skeleton = bool(include and "skeleton" in include)
- auto_skeleton = False
# --- Docs ---
# "full_doc" implies "docs" — entering the docs block whenever either is requested.
@@ -389,24 +402,11 @@ async def _resolve_one_target(
symbols = res.scalars().all()
classes = [s.name for s in symbols if s.kind == "class"]
functions = [s.name for s in symbols if s.kind in ("function", "method")]
- # Skeleton-by-default: for file targets of meaningful size the
- # smart skeleton dominates the bare signature list per token, so
- # the default card upgrades itself. compact=False (the rich
- # symbol card) and full_doc both opt out.
- if not want_skeleton and compact and not want_full_doc:
- total_loc = max((s.end_line or 0 for s in symbols), default=0)
- if total_loc > _SKELETON_AUTO_MIN_LINES:
- want_skeleton = auto_skeleton = True
- # Explicitly requested skeleton suppresses the symbol list up
- # front; the auto default still builds the card and only swaps
- # it out once the skeleton actually resolved (see bottom), so a
- # moved/unreadable source file degrades to the card, not to an
- # error-only response.
- if want_skeleton and not auto_skeleton:
- # The skeleton block already renders every signature with
- # line bounds — repeating the symbol list in docs would
- # roughly double the response for zero information. Keep
- # the cheap title/summary card only.
+ if want_skeleton:
+ # A requested skeleton suppresses the symbol list: it already
+ # renders every signature with line bounds, so repeating the
+ # list in docs would roughly double the response for zero
+ # information. Keep the cheap title/summary card only.
if not docs.get("summary"):
docs["summary"] = _synthesize_structural_summary(target, classes, functions)
elif compact:
@@ -881,31 +881,10 @@ async def _resolve_one_target(
if include and "health" in include:
await _resolve_health(session, repository, target, target_type, result_data)
- # --- Skeleton (distill) — explicit include or the file-target default ---
+ # --- Skeleton (distill) — opt-in only, see the module note ---
if want_skeleton:
await _resolve_skeleton(
session, repository, target, target_type, result_data, repo_root=repo_root
)
- skeleton = result_data.get("skeleton")
- if auto_skeleton and isinstance(skeleton, dict):
- if "error" in skeleton:
- # Auto-upgrade failed (source moved/unreadable) — keep the
- # symbol card the docs block already built and drop the
- # failed block so the default response stays usable.
- result_data.pop("skeleton", None)
- else:
- skeleton["auto"] = True
- skeleton["opt_out_hint"] = (
- "Skeleton is the default for file targets above "
- f"{_SKELETON_AUTO_MIN_LINES} lines. Pass compact=False "
- "for the symbol-list card instead."
- )
- docs_block = result_data.get("docs")
- if isinstance(docs_block, dict):
- # The skeleton renders every signature with line bounds —
- # the symbol list would double the response for zero
- # information.
- docs_block.pop("symbols", None)
- docs_block.pop("symbols_truncated", None)
return result_data
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 0271e02a4..d575df859 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_overview.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_overview.py
@@ -1027,9 +1027,14 @@ async def get_overview(repo: str | None = None, include: list[str] | None = None
result["tool_guide"] = {
"first_call": "get_answer for any how/where/why question; trust "
"confidence=high directly (it is content-grounded).",
- "reading_code": "get_context skeleton (≈37% of a full Read) → "
- "get_symbol for bodies (verified: true = no re-read needed). "
- "Raw Read only for files marked mostly_full or unservable.",
+ # 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",
diff --git a/packages/server/src/repowise/server/mcp_server/tool_risk/assessment.py b/packages/server/src/repowise/server/mcp_server/tool_risk/assessment.py
index f58849526..4ff8a0e1e 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_risk/assessment.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_risk/assessment.py
@@ -166,7 +166,13 @@ def _compute_impact_surface(
"is_entry_point": meta.is_entry_point if meta else False,
}
)
- ranked.sort(key=lambda x: -x["pagerank"])
+ # Path breaks the tie, or the answer is not the same twice. ``visited`` is
+ # a set, so ``ranked`` starts in hash order, and a stable sort keeps that
+ # order wherever pagerank ties — which it does constantly, since most
+ # dependents sit at 0.0. Two identical get_risk calls were returning
+ # different "top 3 most critical modules" (measured: tests/test_progress.py
+ # vs examples/fullscreen.py in the same slot, same tree, minutes apart).
+ ranked.sort(key=lambda x: (-x["pagerank"], x["file_path"]))
ranked = filter_dicts_by_key(ranked, "file_path", exclude_spec)
return ranked[:3]
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 44abe5aaa..973f320dd 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_search.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_search.py
@@ -486,6 +486,33 @@ def _attach_paths(output: list[dict], page_info: dict) -> None:
item["file"] = item["target_path"].split("::", 1)[0]
+def _drop_derivable_page_ids(results: list[dict]) -> list[dict]:
+ """Strip ``page_id`` from every result that can rebuild it, in place.
+
+ A page id is ``compute_page_id(page_type, target_path)`` — literally
+ ``f"{page_type}:{target_path}"`` (``core/generation/models.py``) — and both
+ halves ship in the same row. So the field is 229-369 characters per
+ response, 7.8-10.3% of the payload, restating two of its own siblings. It
+ is ranking plumbing: every internal use above keys the fused dict on it,
+ and none of that needs to reach the wire.
+
+ Conditional rather than unconditional, and the condition is the derivation
+ itself. ``_attach_paths`` writes ``target_path: ""`` for a hit whose Page
+ row did not load, and a row like that cannot be rebuilt — so it keeps its
+ id instead of losing one. The rule is "drop it only where it is provably
+ redundant", which is also the check: if this ever stops firing, the
+ invariant it rests on has changed.
+
+ Consumers rebuild with the same expression; ``ui/src/chat/source-citations``
+ does exactly that, and used to skip any row whose ``page_id`` was missing.
+ """
+ for item in results:
+ derived = f"{item.get('page_type', '')}:{item.get('target_path', '')}"
+ if item.get("page_id") == derived:
+ item.pop("page_id", None)
+ return results
+
+
async def _load_page_info(
session, output: list[dict], *, with_git: bool = False
) -> tuple[dict, set, dict]:
@@ -712,6 +739,8 @@ async def _federated_search(
# name files.
if candidates := file_candidates(all_results, limit=limit):
response["candidates"] = candidates
+ # Last, so nothing above has to know the field is on its way out.
+ _drop_derivable_page_ids(output)
return response
@@ -917,6 +946,8 @@ async def _structured_search(
)
if grep_hint and not results:
response["grep_hint"] = grep_hint
+ # Last, so nothing above has to know the field is on its way out.
+ _drop_derivable_page_ids(results)
return response
@@ -1044,4 +1075,6 @@ async def search_codebase(
response["candidates"] = candidates
if grep_hint and not output:
response["grep_hint"] = grep_hint
+ # Last, so nothing above has to know the field is on its way out.
+ _drop_derivable_page_ids(output)
return response
diff --git a/packages/ui/src/chat/source-citations.tsx b/packages/ui/src/chat/source-citations.tsx
index d714472ba..7907c4e28 100644
--- a/packages/ui/src/chat/source-citations.tsx
+++ b/packages/ui/src/chat/source-citations.tsx
@@ -35,7 +35,15 @@ export function extractSources(
if (tc.name === "search_codebase") {
const results = (result.results as Array<Record<string, unknown>>) ?? [];
for (const r of results) {
- const pageId = r.page_id as string;
+ // `page_id` is `${page_type}:${target_path}`, and the tool now omits it
+ // wherever those two rebuild it. Derive rather than skip: the previous
+ // `const pageId = r.page_id` dropped the whole row — and its citation —
+ // for any result without one. Same fallback the get_context branch uses.
+ const pageType = r.page_type as string | undefined;
+ const targetPath = r.target_path as string | undefined;
+ const pageId =
+ (r.page_id as string | undefined) ??
+ (pageType && targetPath ? `${pageType}:${targetPath}` : "");
if (!pageId || seen.has(pageId)) continue;
seen.add(pageId);
sources.push({
diff --git a/tests/unit/cli/test_tool_adapter_commands.py b/tests/unit/cli/test_tool_adapter_commands.py
index 5b375e6a8..c2d7e4f8f 100644
--- a/tests/unit/cli/test_tool_adapter_commands.py
+++ b/tests/unit/cli/test_tool_adapter_commands.py
@@ -325,7 +325,16 @@ def test_ask_projection_is_a_fraction_of_the_payload():
assert trimmed * 3 < full, f"trim saved too little: {trimmed} of {full}"
-def test_context_projection_keeps_the_skeleton_shape_without_its_text():
+def test_context_projection_passes_a_requested_skeleton_through_whole():
+ """A skeleton in the card was asked for by name, so it survives the trim.
+
+ This used to strip ``skeleton.text``, and that was right while the tool
+ auto-upgraded every file target above 80 lines: the text was 73-91% of the
+ payload and nobody had requested it. The tool no longer auto-upgrades, so
+ the only way a skeleton reaches this function is ``--include skeleton``,
+ and trimming its text back out would make that flag inert — the same
+ failure the include passthrough two tests below exists to prevent.
+ """
out = project_context(CONTEXT_PAYLOAD, ("a.py",))
card = out["targets"]["a.py"]
assert card["title"] == "File: a.py"
@@ -338,11 +347,8 @@ def test_context_projection_keeps_the_skeleton_shape_without_its_text():
unknown = {"target": "a.py", "freshness": {"is_stale": None}}
assert "stale" not in project_context({"targets": {"a.py": unknown}}, ("a.py",))["targets"]["a.py"]
assert card["episodes"] == 4
- assert card["skeleton"] == {
- "mode": "smart", "tokens": 100, "full_tokens": 400,
- "pct_of_full": 25.0, "verified": True, "bodies_kept": ["f"],
- }
- assert "z" * 100 not in json.dumps(out), "skeleton text survived the trim"
+ assert card["skeleton"] == CONTEXT_PAYLOAD["targets"]["a.py"]["skeleton"]
+ assert "z" * 100 in card["skeleton"]["text"], "the requested source went missing"
assert "parent_page" not in card
diff --git a/tests/unit/server/mcp/test_answer_calibration.py b/tests/unit/server/mcp/test_answer_calibration.py
index 1849b4437..ae24fdc3b 100644
--- a/tests/unit/server/mcp/test_answer_calibration.py
+++ b/tests/unit/server/mcp/test_answer_calibration.py
@@ -1044,8 +1044,15 @@ async def test_non_dominant_best_guesses_carry_candidate_excerpts(setup_mcp, mon
A pointers-only reply makes the agent re-acquire all content natively
(observed as an 8-15 call Grep/Read spree in agent transcripts), so the
- best_guesses folded into a non-dominant reply carry the top candidates'
- actual page content beside the synthesized prose.
+ non-dominant reply ships the top candidates' actual page content beside
+ the synthesized prose.
+
+ **Once, not twice.** ``best_guesses`` and ``retrieval`` used to slice the
+ same 1,500-character page excerpt for the same file — 21.3% of one measured
+ payload, duplicated byte for byte — so the guess copy is dropped wherever
+ ``retrieval`` already carries it. The content requirement above is
+ unchanged and is what the second half of this test pins: the excerpt is
+ still in the response, in exactly one place.
"""
import repowise.server.mcp_server as mcp_mod
import repowise.server.mcp_server.tool_answer.answer as answer_mod
@@ -1083,7 +1090,13 @@ async def test_non_dominant_best_guesses_carry_candidate_excerpts(setup_mcp, mon
assert result["confidence"] == "medium" # non-dominant ceiling
assert result["answer"]
top = result["best_guesses"][0]
- assert top["excerpt"].startswith("Page content for pkg/alpha/one.py")
+ 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 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_context.py b/tests/unit/server/mcp/test_context.py
index 77bdd32f9..296124398 100644
--- a/tests/unit/server/mcp/test_context.py
+++ b/tests/unit/server/mcp/test_context.py
@@ -330,9 +330,14 @@ def test_truncate_noop_when_under_budget():
"_meta": {},
}
out = _truncate_to_budget(small)
- assert out["truncated"] is False
- assert out["dropped_targets"] == []
- assert out["dropped_symbols"] == {}
+ # Absent, not false. ``truncated: false`` plus two empty containers is 60
+ # characters of "nothing happened" on every response that fits — which is
+ # nearly all of them. Both projections read these with ``.get()``, so empty
+ # and absent are the same answer to a consumer.
+ assert not out.get("truncated")
+ assert not out.get("dropped_targets")
+ assert not out.get("dropped_symbols")
+ assert "truncated" not in out
assert "content_md" not in out["targets"]["a.py"]["docs"] # wasn't there anyway
diff --git a/tests/unit/server/mcp/test_context_skeleton.py b/tests/unit/server/mcp/test_context_skeleton.py
index d92aea2d3..8fdf9cbaa 100644
--- a/tests/unit/server/mcp/test_context_skeleton.py
+++ b/tests/unit/server/mcp/test_context_skeleton.py
@@ -151,28 +151,59 @@ async def test_skeleton_missing_source_file(setup_mcp, tmp_path, monkeypatch):
@pytest.mark.asyncio
-async def test_skeleton_is_default_for_large_file_targets(setup_mcp, tmp_path, monkeypatch):
- # service.py spans 100 lines (> the 80-line threshold): the default card
- # auto-upgrades to the skeleton and drops the redundant symbol list.
+async def test_no_skeleton_without_an_explicit_include(setup_mcp, tmp_path, monkeypatch):
+ """A file target serves the symbol card, never source bytes, unless asked.
+
+ service.py spans 100 lines and used to auto-upgrade to a skeleton above an
+ 80-line threshold, on the claim that the skeleton beat the bare signature
+ list per token. Re-measured on pinned Textualize/rich the claim is
+ inverted — rich/ansi.py's card is 2,171 characters against 6,585 with the
+ auto skeleton, of which the skeleton text alone is 5,295 — so source is
+ opt-in. See the note on the retired constant in ``tool_context/targets``.
+ """
from repowise.server.mcp_server import _state, get_context
_write_source(tmp_path)
monkeypatch.setattr(_state, "_repo_path", str(tmp_path))
result = await get_context(["src/auth/service.py"])
card = result["targets"]["src/auth/service.py"]
- sk = card["skeleton"]
- assert sk["auto"] is True
- assert "compact=False" in sk["opt_out_hint"]
- assert "class AuthService:" in sk["text"]
- assert "symbols" not in card["docs"]
- # Summary and freshness still ride along.
+ assert "skeleton" not in card
+ # The navigation the skeleton used to displace survives: names,
+ # signatures, line numbers, and the cheap card around them.
+ assert card["docs"]["symbols"]
assert card["docs"].get("summary") is not None
assert "freshness" in card
+async def test_include_skeleton_still_serves_the_full_text(setup_mcp, tmp_path, monkeypatch):
+ """The other direction: the opt-in path is untouched and carries the text."""
+ from repowise.server.mcp_server import _state, get_context
+
+ _write_source(tmp_path)
+ monkeypatch.setattr(_state, "_repo_path", str(tmp_path))
+ result = await get_context(["src/auth/service.py"], include=["skeleton"])
+ card = result["targets"]["src/auth/service.py"]
+ assert "class AuthService:" in card["skeleton"]["text"]
+ assert card["skeleton"]["verified"] is True
+
+
+async def test_untruncated_response_omits_the_empty_truncation_keys(
+ setup_mcp, tmp_path, monkeypatch
+):
+ """60 characters of "nothing happened", on every response that fits."""
+ from repowise.server.mcp_server import _state, get_context
+
+ monkeypatch.setattr(_state, "_repo_path", str(tmp_path))
+ result = await get_context(["src/db/models.py"])
+ assert not result.get("truncated")
+ for key in ("truncated", "dropped_targets", "dropped_symbols"):
+ assert key not in result, f"{key} shipped on an untruncated response"
+
+
@pytest.mark.asyncio
async def test_small_file_keeps_symbol_card(setup_mcp, tmp_path, monkeypatch):
- # models.py's symbols end at line 30 — below the threshold, no skeleton.
from repowise.server.mcp_server import _state, get_context
monkeypatch.setattr(_state, "_repo_path", str(tmp_path))
@@ -183,7 +214,7 @@ async def test_small_file_keeps_symbol_card(setup_mcp, tmp_path, monkeypatch):
@pytest.mark.asyncio
-async def test_compact_false_opts_out_of_auto_skeleton(setup_mcp, tmp_path, monkeypatch):
+async def test_compact_false_still_serves_no_skeleton(setup_mcp, tmp_path, monkeypatch):
from repowise.server.mcp_server import _state, get_context
_write_source(tmp_path)
@@ -195,11 +226,9 @@ async def test_compact_false_opts_out_of_auto_skeleton(setup_mcp, tmp_path, monk
@pytest.mark.asyncio
-async def test_auto_skeleton_falls_back_to_card_when_source_missing(
- setup_mcp, tmp_path, monkeypatch
-):
- # Nothing on disk: the auto-upgrade must degrade to the symbol card, not
- # to an error-only response (explicit include=["skeleton"] still errors).
+async def test_default_card_survives_a_missing_source_file(setup_mcp, tmp_path, monkeypatch):
+ # Nothing on disk. The default card never touches the source, so it is
+ # unaffected; explicit include=["skeleton"] still errors (test above).
from repowise.server.mcp_server import _state, get_context
monkeypatch.setattr(_state, "_repo_path", str(tmp_path))
diff --git a/tests/unit/server/mcp/test_payload_cuts.py b/tests/unit/server/mcp/test_payload_cuts.py
new file mode 100644
index 000000000..5812714b3
--- /dev/null
+++ b/tests/unit/server/mcp/test_payload_cuts.py
@@ -0,0 +1,205 @@
+"""Payload cuts: each one is lossless, and each proof is the loss test.
+
+A tool result is new text entering a long, already-cached conversation, so it
+is billed at the cache-*write* rate — far above the rate at which the rest of
+the prompt is re-read, and paid again for every result. A field the agent does
+not act on is therefore not free; it is some of the most expensive text in the
+session, and it costs more the later in a session it arrives.
+
+Every test here pins the same shape: **the cut fires where the information is
+redundant, and does NOT fire where it is the only copy.** A one-directional
+test passes just as happily on a cut that silently ate the payload, which is
+the failure mode each of these changes was designed around.
+"""
+
+from __future__ import annotations
+
+from repowise.server.mcp_server._budget.budgeter import truncate_to_budget
+from repowise.server.mcp_server.tool_answer.answer import (
+ _build_best_guesses,
+ _drop_duplicated_guess_excerpts,
+ _trim_served_payload,
+)
+from repowise.server.mcp_server.tool_answer.retrieval import _CANDIDATE_LIMIT
+from repowise.server.mcp_server.tool_search import _drop_derivable_page_ids
+
+# ---------------------------------------------------------------------------
+# search_codebase.results[].page_id — derivable from two of its own siblings
+# ---------------------------------------------------------------------------
+
+
+def test_page_id_dropped_when_page_type_and_target_path_rebuild_it():
+ results = [
+ {
+ "page_id": "file_page:rich/ansi.py",
+ "page_type": "file_page",
+ "target_path": "rich/ansi.py",
+ "title": "ansi",
+ }
+ ]
+ _drop_derivable_page_ids(results)
+ assert "page_id" not in results[0]
+ # Lossless: the consumer rebuilds it from what is still there.
+ assert f"{results[0]['page_type']}:{results[0]['target_path']}" == "file_page:rich/ansi.py"
+
+
+def test_page_id_kept_when_it_cannot_be_rebuilt():
+ """The other direction, and it is a real case, not a hypothetical.
+
+ ``_attach_paths`` writes ``target_path: ""`` for a hit whose Page row did
+ not load. Dropping the id there would lose the only handle the row has.
+ """
+ orphan = {"page_id": "file_page:rich/gone.py", "page_type": "file_page", "target_path": ""}
+ renamed = {"page_id": "module_page:rich", "page_type": "file_page", "target_path": "rich"}
+ _drop_derivable_page_ids([orphan, renamed])
+ assert orphan["page_id"] == "file_page:rich/gone.py"
+ assert renamed["page_id"] == "module_page:rich"
+
+
+def test_symbol_qualified_page_ids_still_rebuild():
+ """A symbol_spotlight's target_path is ``file.py::Symbol`` — still derivable."""
+ results = [
+ {
+ "page_id": "symbol_spotlight:rich/ansi.py::AnsiDecoder",
+ "page_type": "symbol_spotlight",
+ "target_path": "rich/ansi.py::AnsiDecoder",
+ }
+ ]
+ _drop_derivable_page_ids(results)
+ assert "page_id" not in results[0]
+
+
+# ---------------------------------------------------------------------------
+# get_answer.best_guesses[].excerpt — the same slab retrieval[] already carries
+# ---------------------------------------------------------------------------
+
+
+def test_guess_excerpt_dropped_when_retrieval_carries_it():
+ payload = {
+ "retrieval": [{"path": "a.py", "excerpt": "line one\nline two\nline three"}],
+ "best_guesses": [{"file": "a.py", "score": 1.0, "excerpt": "line two\nline three"}],
+ }
+ _drop_duplicated_guess_excerpts(payload)
+ assert "excerpt" not in payload["best_guesses"][0]
+ # Still in the response, exactly once.
+ assert "line two" in payload["retrieval"][0]["excerpt"]
+
+
+def test_guess_excerpt_kept_when_retrieval_is_empty():
+ """The abstain path ships ``retrieval: []``, so the guess IS the content.
+
+ A measured payload carried 4,667 characters of guess excerpt with an empty
+ retrieval block. An unconditional drop would have deleted the answer.
+ """
+ payload = {
+ "retrieval": [],
+ "best_guesses": [{"file": "a.py", "score": 1.0, "excerpt": "the only copy"}],
+ }
+ _drop_duplicated_guess_excerpts(payload)
+ assert payload["best_guesses"][0]["excerpt"] == "the only copy"
+
+
+def test_guess_excerpt_kept_when_retrieval_carries_a_different_file():
+ payload = {
+ "retrieval": [{"path": "b.py", "excerpt": "unrelated content"}],
+ "best_guesses": [{"file": "a.py", "score": 1.0, "excerpt": "a.py content"}],
+ }
+ _drop_duplicated_guess_excerpts(payload)
+ assert payload["best_guesses"][0]["excerpt"] == "a.py content"
+
+
+def test_drop_is_a_noop_without_best_guesses():
+ payload = {"answer": "prose", "retrieval": [{"path": "a.py", "excerpt": "x"}]}
+ assert _drop_duplicated_guess_excerpts(payload) == payload
+
+
+def test_null_domain_penalty_is_absent_not_null():
+ plain = _build_best_guesses([{"target_path": "a.py", "score": 0.5}])
+ assert "domain_penalty" not in plain[0]
+ penalised = _build_best_guesses(
+ [{"target_path": "a.py", "score": 0.5, "_domain_penalty": "ui question; cross-domain"}]
+ )
+ assert penalised[0]["domain_penalty"] == "ui question; cross-domain"
+
+
+# ---------------------------------------------------------------------------
+# get_answer.candidates — 20 rows measured at up to 39.9% of the payload
+# ---------------------------------------------------------------------------
+
+
+def test_candidate_limit_is_capped():
+ # Not an equality assert on 5: the number is a judgement call and may move
+ # again. What must not come back is the 20 that made this block 3,107-3,279
+ # characters, up to 39.9% of a measured get_answer payload.
+ assert _CANDIDATE_LIMIT <= 8
+
+
+def test_cached_payload_is_capped_on_the_way_out():
+ """A cache row written at 20 rows must not serve 20 rows.
+
+ Capping only where the block is built left the cap unreachable for every
+ already-cached answer, and the tree used to re-measure this change came
+ back byte-identical because of exactly that.
+ """
+ payload = {"candidates": [{"path": f"f{i}.py"} for i in range(20)]}
+ _trim_served_payload(payload)
+ assert len(payload["candidates"]) == _CANDIDATE_LIMIT
+ # Head kept, so the best-ranked file is still the one described.
+ assert payload["candidates"][0]["path"] == "f0.py"
+
+
+def test_trim_leaves_a_short_candidate_list_alone():
+ payload = {"candidates": [{"path": "a.py"}, {"path": "b.py"}]}
+ _trim_served_payload(payload)
+ assert len(payload["candidates"]) == 2
+
+
+# ---------------------------------------------------------------------------
+# The empty truncation keys
+# ---------------------------------------------------------------------------
+
+
+def test_truncation_keys_absent_when_nothing_was_dropped():
+ out = truncate_to_budget({"targets": {"a.py": {"target": "a.py"}}, "_meta": {}})
+ for key in ("truncated", "dropped_targets", "dropped_symbols"):
+ assert key not in out
+
+
+# ---------------------------------------------------------------------------
+# get_risk.impact_surface — the same call must give the same answer
+# ---------------------------------------------------------------------------
+
+
+def test_impact_surface_is_stable_across_equal_pagerank():
+ """Ties broke on set-iteration order, so the "top 3" changed between calls.
+
+ Found by a payload-parity run: two identical `get_risk` calls minutes apart
+ on the same tree named `tests/test_progress.py` and `examples/fullscreen.py`
+ in the same slot. `visited` is a set and the sort is stable, so wherever
+ pagerank ties — which is most of the graph, at 0.0 — the order was whatever
+ hashing produced that process.
+ """
+ from repowise.server.mcp_server.tool_risk.assessment import _compute_impact_surface
+
+ deps = {"t.py": {"b.py", "a.py", "c.py", "d.py"}}
+ first = _compute_impact_surface("t.py", deps, {})
+ # Same inputs, a set built in a different insertion order.
+ deps2 = {"t.py": {"d.py", "c.py", "a.py", "b.py"}}
+ second = _compute_impact_surface("t.py", deps2, {})
+
+ assert [r["file_path"] for r in first] == ["a.py", "b.py", "c.py"]
+ assert first == second
+
+
+def test_truncation_keys_present_when_something_was_dropped():
+ """The other direction. A silent drop is the one failure this must not have."""
+ targets = {
+ f"file_{i}.py": {
+ "target": f"file_{i}.py",
+ "docs": {"symbols": [{"name": f"sym_{n}", "doc": "x" * 400} for n in range(40)]},
+ }
+ for i in range(30)
+ }
+ out = truncate_to_budget({"targets": targets, "_meta": {}}, char_budget=2_000)
+ assert out["truncated"] is True
+ assert out["dropped_targets"] or out["dropped_symbols"]
diff --git a/tests/unit/server/mcp/test_tombstones.py b/tests/unit/server/mcp/test_tombstones.py
index 0deccc26b..be75c1d6e 100644
--- a/tests/unit/server/mcp/test_tombstones.py
+++ b/tests/unit/server/mcp/test_tombstones.py
@@ -106,7 +106,11 @@ async def test_search_drops_tombstoned_pages(setup_mcp, session, monkeypatch):
mcp_mod._vector_store.search = fake_search
result = await search_codebase("auth service")
- ids = [r["page_id"] for r in result["results"]]
+ # ``page_id`` is omitted from any result that can rebuild it from
+ # ``page_type`` + ``target_path``, which is every result whose Page row
+ # loaded. Reconstruct rather than read — the tombstone filter itself is
+ # unchanged and still keys on the id internally.
+ ids = [f"{r['page_type']}:{r['target_path']}" for r in result["results"]]
assert "file_page:src/auth/service.py" not in ids
assert "file_page:src/db/models.py" in ids