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.

refactor(mcp): split tool_context.py into a package + fix truncation O(n^2) (#263)

Swati Ahuja6a0d8d87f4d0
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context.py b/packages/server/src/repowise/server/mcp_server/tool_context.py
deleted file mode 100644
index af855fe11..000000000
--- a/packages/server/src/repowise/server/mcp_server/tool_context.py
+++ /dev/null
@@ -1,1342 +0,0 @@
-"""MCP Tool: get_context — relationships and triage signals for files / modules / symbols.
-
-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.
-
-Optional ``include`` parameter widens the response:
- - include=["full_doc"] → full wiki markdown content
- - include=["callers"] → who calls this symbol (symbol targets only)
- - include=["callees"] → what this symbol calls (symbol targets only)
- - include=["ownership"] → primary owner, bus factor, contributor count
- - include=["last_change"]→ last commit date and author
- - include=["metrics"] → PageRank, betweenness, percentile ranks
- - include=["community"] → community membership + neighbors
- - include=["decisions"] → full decision records (default returns titles only)
-"""
-
-from __future__ import annotations
-
-import asyncio
-import json
-import logging
-from typing import Any
-
-logger = logging.getLogger(__name__)
-
-# --- Output size budget -------------------------------------------------------
-# The Claude Code harness rejects MCP tool results whose stringified form exceeds
-# ~10k tokens (it refuses to inline them and then refuses to Read the spilled
-# file). When that happens the agent falls back to multiple get_symbol calls,
-# each of which re-plays the cached system prompt — a significant cost driver
-# on dense files in long multi-turn agent sessions.
-#
-# We therefore cap get_context output well below that ceiling. 8000 tokens
-# leaves headroom for the wrapping JSON envelope and _meta fields the harness
-# adds on top. The estimator is intentionally dependency-free: 4 chars/token is
-# the widely-quoted average for English + code on BPE tokenizers and is within
-# ~20% of tiktoken for typical wiki content. Precise counting is unnecessary
-# because we only need to stay comfortably under the hard limit.
-_TOKEN_BUDGET = 8000
-_CHARS_PER_TOKEN = 4
-_CHAR_BUDGET = _TOKEN_BUDGET * _CHARS_PER_TOKEN
-
-from sqlalchemy import select
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from repowise.core.persistence.crud import (
- get_all_file_metrics,
- get_community_members,
- get_cross_community_edges,
- get_graph_edges_for_node,
- get_graph_node,
- get_graph_nodes_by_ids,
- get_kg_layers,
- get_kg_tour_steps,
- get_node_degree_counts,
-)
-from repowise.core.persistence.database import get_session
-from repowise.core.persistence.decision_graph import get_governing_decisions
-from repowise.core.persistence.models import (
- CoverageFile,
- DecisionRecord,
- GitMetadata,
- GraphEdge,
- GraphNode,
- HealthFileMetric,
- HealthFinding,
- Page,
- Repository,
- WikiSymbol,
-)
-from repowise.server.mcp_server import _state
-from repowise.server.mcp_server._helpers import (
- _get_repo,
- _resolve_repo_context,
- _unsupported_repo_all,
-)
-from repowise.server.mcp_server._meta import build_meta as _build_meta
-from repowise.server.mcp_server._meta import context_hint as _context_hint
-from repowise.core.registry import mcp_tool_registry as mcp
-
-# Minimum confidence for call edges to filter false positives
-_MIN_CALL_CONFIDENCE = 0.7
-
-
-def _synthesize_structural_summary(file_path: str, classes: list[str], functions: list[str]) -> str:
- """Build a deterministic 1-line summary when no LLM-generated summary exists.
-
- Used in --index-only mode (no wiki pages) and as a fallback when an LLM
- page predates the summary column. Always returns a non-empty string so the
- agent never sees a missing field.
- """
- name = file_path.rsplit("/", 1)[-1]
- parts: list[str] = []
- if classes:
- head = ", ".join(classes[:3])
- more = f" (+{len(classes) - 3} more)" if len(classes) > 3 else ""
- parts.append(f"defines {head}{more}")
- if functions:
- head = ", ".join(functions[:3])
- more = f" (+{len(functions) - 3} more)" if len(functions) > 3 else ""
- parts.append(f"function{'s' if len(functions) > 1 else ''} {head}{more}")
- if not parts:
- return f"{name}: empty or non-symbol file"
- return f"{name}: " + "; ".join(parts) + "."
-
-
-async def _resolve_one_target(
- session: AsyncSession,
- repository: Repository,
- target: str,
- include: set[str] | None,
- compact: bool = False,
-) -> dict:
- """Resolve a single target and return its full context."""
- repo_id = repository.id
- result_data: dict[str, Any] = {}
-
- # --- Determine target type ---
- # 1. Try file page (most common)
- page_id = f"file_page:{target}"
- page = await session.get(Page, page_id)
- target_type = None
- file_path_for_git: str | None = None
-
- if page and page.repository_id == repo_id:
- target_type = "file"
- file_path_for_git = target
- else:
- # 1b. Normalise directory targets: strip trailing slash and try module
- clean_target = target.rstrip("/")
- # 2. Try module page (exact, then cleaned, then partial)
- res = await session.execute(
- select(Page).where(
- Page.repository_id == repo_id,
- Page.page_type == "module_page",
- Page.target_path == target,
- )
- )
- page = res.scalar_one_or_none()
- if page is None and clean_target != target:
- res = await session.execute(
- select(Page).where(
- Page.repository_id == repo_id,
- Page.page_type == "module_page",
- Page.target_path == clean_target,
- )
- )
- page = res.scalar_one_or_none()
- if page is None:
- # Partial match fallback for modules
- res = await session.execute(
- select(Page).where(
- Page.repository_id == repo_id,
- Page.page_type == "module_page",
- Page.target_path.contains(clean_target),
- )
- )
- page = res.scalar_one_or_none()
- if page:
- target_type = "module"
- else:
- # 3. Try symbol (exact then fuzzy)
- res = await session.execute(
- select(WikiSymbol).where(
- WikiSymbol.repository_id == repo_id,
- WikiSymbol.name == target,
- )
- )
- sym_matches = list(res.scalars().all())
- if not sym_matches:
- res = await session.execute(
- select(WikiSymbol)
- .where(
- WikiSymbol.repository_id == repo_id,
- WikiSymbol.name.ilike(f"%{target}%"),
- )
- .limit(10)
- )
- sym_matches = list(res.scalars().all())
- if sym_matches:
- target_type = "symbol"
- file_path_for_git = sym_matches[0].file_path
- else:
- # 4. Try file page by target_path search
- res = await session.execute(
- select(Page).where(
- Page.repository_id == repo_id,
- Page.page_type == "file_page",
- Page.target_path == target,
- )
- )
- page = res.scalar_one_or_none()
- if page:
- target_type = "file"
- file_path_for_git = target
-
- if target_type is None:
- # Fallback 1: index-only mode (no wiki pages) — return graph node + symbols if present
- res = await session.execute(
- select(GraphNode).where(
- GraphNode.repository_id == repo_id,
- GraphNode.node_id == target,
- )
- )
- gnode = res.scalar_one_or_none()
- if gnode is not None:
- target_type = "file"
- file_path_for_git = target
- page = None # no wiki page; subsequent blocks must guard for this
-
- # Fallback 2: check git_metadata — file may exist but have no wiki page AND no graph node
- if target_type is None:
- res = await session.execute(
- select(GitMetadata).where(
- GitMetadata.repository_id == repo_id,
- GitMetadata.file_path == target,
- )
- )
- meta = res.scalar_one_or_none()
- if meta:
- return {
- "target": target,
- "error": (
- f"'{target}' exists in the repository but has no wiki page. "
- "This usually means the file has too few symbols or is below "
- "the PageRank threshold. Run `repowise update` to regenerate docs."
- ),
- "exists_in_git": True,
- "last_commit_at": meta.last_commit_at.isoformat()
- if meta.last_commit_at
- else None,
- "primary_owner": meta.primary_owner_name,
- "is_hotspot": meta.is_hotspot,
- }
-
- # Fallback 3: fuzzy path suggestions — match by filename or partial path.
- # Only runs if the prior fallbacks didn't resolve the target.
- if target_type is None:
- # For directory-like targets, suggest files within that directory
- dir_prefix = clean_target.rstrip("/") + "/"
- res = await session.execute(
- select(GitMetadata.file_path)
- .where(
- GitMetadata.repository_id == repo_id,
- GitMetadata.file_path.like(f"{dir_prefix}%"),
- )
- .limit(5)
- )
- suggestions = [row[0] for row in res.all()]
- if not suggestions:
- # Fall back to filename / partial path match
- tail = target.rsplit("/", 1)[-1]
- res = await session.execute(
- select(GitMetadata.file_path)
- .where(
- GitMetadata.repository_id == repo_id,
- GitMetadata.file_path.contains(tail),
- )
- .limit(5)
- )
- suggestions = [row[0] for row in res.all() if row[0] != target]
- if suggestions:
- return {
- "target": target,
- "error": f"Target not found: '{target}'",
- "suggestions": suggestions,
- }
- return {"target": target, "error": f"Target not found: '{target}'"}
-
- result_data["target"] = target
- result_data["type"] = target_type
-
- # --- Docs ---
- # "full_doc" implies "docs" — entering the docs block whenever either is requested.
- if include is None or "docs" in include or "full_doc" in include:
- want_full_doc = bool(include and "full_doc" in include)
- docs: dict[str, Any] = {}
- if target_type == "file":
- if page is not None:
- docs["title"] = page.title
- docs["summary"] = page.summary or ""
- if want_full_doc:
- docs["content_md"] = page.content
- if page.human_notes:
- docs["human_notes"] = page.human_notes
- # Symbols in this file
- res = await session.execute(
- select(WikiSymbol).where(
- WikiSymbol.repository_id == repo_id,
- WikiSymbol.file_path == 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")]
- if compact:
- # Compact mode: name+kind+signature+line+symbol_id only. Drops
- # docstrings, line ranges, structure, and imported_by — those
- # live behind compact=False or include= flags. The symbol_id
- # is the canonical handle the caller pipes straight into
- # get_symbol when it wants bytes.
- #
- # Cap at 40 symbols so a dense generated file (protobuf
- # wrappers, vendored libs) can't blow the triage card past
- # the agent's budget. Order matches WikiSymbol.start_line
- # (assigned at index time), so the head is the navigationally
- # useful slice.
- symbol_cap = 40
- visible = list(symbols)[:symbol_cap]
- docs["symbols"] = [
- {
- "name": s.name,
- "kind": s.kind,
- "signature": s.signature,
- "line": s.start_line,
- "symbol_id": s.symbol_id,
- }
- for s in visible
- ]
- if len(symbols) > symbol_cap:
- docs["symbols_truncated"] = {
- "shown": symbol_cap,
- "total": len(symbols),
- "hint": "Call with compact=False or include=['full_doc'] for the full list.",
- }
- if not docs.get("summary"):
- docs["summary"] = _synthesize_structural_summary(target, classes, functions)
- else:
- docs["symbols"] = [
- {
- "name": s.name,
- "kind": s.kind,
- "signature": s.signature,
- "start_line": s.start_line,
- "end_line": s.end_line,
- "docstring": (s.docstring or "")[:400],
- }
- for s in symbols
- ]
- # Structure summary block — quick scan of what's in the file
- total_loc = max((s.end_line for s in symbols), default=0)
- avg_complexity = (
- sum(s.complexity_estimate for s in symbols) / len(symbols) if symbols else 0
- )
- docs["structure"] = {
- "classes": classes,
- "functions": functions,
- "symbol_count": len(symbols),
- "total_loc": total_loc,
- "avg_complexity": round(avg_complexity, 2),
- }
- # Fallback summary: if no Page (index-only mode) or page.summary
- # is empty, synthesize a deterministic one-liner from structure.
- if not docs.get("summary"):
- docs["summary"] = _synthesize_structural_summary(target, classes, functions)
- # Importers
- res = await session.execute(
- select(GraphEdge).where(
- GraphEdge.repository_id == repo_id,
- GraphEdge.target_node_id == target,
- )
- )
- importers = res.scalars().all()
- docs["imported_by"] = [e.source_node_id for e in importers]
-
- # Community info (compact=False only, ~80 bytes)
- res = await session.execute(
- select(GraphNode).where(
- GraphNode.repository_id == repo_id,
- GraphNode.node_id == target,
- )
- )
- gn = res.scalar_one_or_none()
- if gn and gn.community_id is not None:
- _cmeta: dict[str, Any] = {}
- try:
- _cmeta = json.loads(gn.community_meta_json or "{}")
- except (json.JSONDecodeError, TypeError):
- pass
- docs["community"] = {
- "id": gn.community_id,
- "label": _cmeta.get("label", ""),
- }
-
- elif target_type == "module":
- docs["title"] = page.title
- docs["summary"] = page.summary or ""
- if want_full_doc:
- docs["content_md"] = page.content
- # Child file pages
- res = await session.execute(
- select(Page).where(
- Page.repository_id == repo_id,
- Page.page_type == "file_page",
- Page.target_path.like(f"{page.target_path}/%"),
- )
- )
- file_pages = res.scalars().all()
- docs["files"] = [
- {
- "path": f.target_path,
- "description": f.title,
- "confidence_score": f.confidence,
- }
- for f in file_pages
- ]
-
- elif target_type == "symbol":
- sym = sym_matches[0] # type: ignore[possibly-undefined]
- docs["name"] = sym.name
- docs["qualified_name"] = sym.qualified_name
- docs["kind"] = sym.kind
- docs["signature"] = sym.signature
- docs["file_path"] = sym.file_path
- docs["docstring"] = sym.docstring or ""
- # File page summary (full content gated behind include=["full_doc"])
- sym_page_id = f"file_page:{sym.file_path}"
- sym_page = await session.get(Page, sym_page_id)
- if sym_page is not None:
- docs["file_summary"] = sym_page.summary or ""
- if want_full_doc:
- docs["documentation"] = sym_page.content
- # Used by
- res = await session.execute(
- select(GraphEdge).where(
- GraphEdge.repository_id == repo_id,
- GraphEdge.target_node_id == sym.file_path,
- )
- )
- edges = res.scalars().all()
- docs["used_by"] = [e.source_node_id for e in edges][:20]
- # Candidates
- if len(sym_matches) > 1: # type: ignore[possibly-undefined]
- docs["candidates"] = [
- {"name": m.name, "kind": m.kind, "file_path": m.file_path}
- for m in sym_matches[1:5] # type: ignore[possibly-undefined]
- ]
-
- result_data["docs"] = docs
-
- # --- Triage signals (always on) ---------------------------------------
- # Two single-bit-ish pointers the agent uses to decide its next move:
- # * ``hotspot``: lights the way to ``get_risk`` for files in the 95th+
- # churn percentile. Just the boolean — the full risk dossier stays
- # in ``get_risk`` so the triage card doesn't grow.
- # * ``decision_records``: titles only, no body. Lights the way to
- # ``get_why``. We deliberately don't inline the rationale here;
- # duplicating it across every ``get_context`` response bloats the
- # cached prompt prefix and defeats the split between the two tools.
- #
- # Cheap: two short queries piggybacking on the session we already opened.
- triage_path = file_path_for_git
- if target_type == "module" and page:
- triage_path = page.target_path
- if triage_path:
- triage_meta_res = await session.execute(
- select(GitMetadata.is_hotspot).where(
- GitMetadata.repository_id == repo_id,
- GitMetadata.file_path == triage_path,
- )
- )
- triage_meta = triage_meta_res.scalar_one_or_none()
- result_data["hotspot"] = bool(triage_meta) if triage_meta is not None else False
-
- # Bounded graph-link query — replaces full Python scan over all rows.
- governing: list[DecisionRecord] = []
- seen_ids: set[str] = set()
- for lookup_node in dict.fromkeys(
- [triage_path, target] if triage_path != target else [triage_path]
- ):
- if not lookup_node:
- continue
- for dr in await get_governing_decisions(session, repo_id, lookup_node):
- if dr.id not in seen_ids:
- seen_ids.add(dr.id)
- governing.append(dr)
- if governing:
- result_data["decision_records"] = [dr.title for dr in governing[:5]]
- result_data["decision_records_hint"] = (
- "Decisions touch this file. Call get_why(targets=[...]) for rationale."
- )
- # Compact enriched list — highest-confidence first, capped at 5.
- governing_sorted = sorted(governing, key=lambda d: -(d.confidence or 0.0))
- result_data["governing_decisions"] = [
- {
- "id": dr.id,
- "title": dr.title,
- "status": dr.status,
- "staleness_score": dr.staleness_score,
- "verification": dr.verification,
- "stale": bool(dr.status == "active" and (dr.staleness_score or 0.0) >= 0.5),
- }
- for dr in governing_sorted[:5]
- ]
-
- # --- Ownership ---
- if include is None or "ownership" in include:
- ownership: dict[str, Any] = {}
- git_path = file_path_for_git
- if target_type == "module" and page:
- git_path = page.target_path
- if git_path:
- res = await session.execute(
- select(GitMetadata).where(
- GitMetadata.repository_id == repo_id,
- GitMetadata.file_path == git_path,
- )
- )
- meta = res.scalar_one_or_none()
- if meta:
- ownership["primary_owner"] = meta.primary_owner_name
- ownership["owner_pct"] = meta.primary_owner_commit_pct
- ownership["contributor_count"] = getattr(meta, "contributor_count", 0) or len(
- json.loads(meta.top_authors_json)
- )
- ownership["bus_factor"] = getattr(meta, "bus_factor", 0) or 0
- # Recent owner (who maintains this file now)
- recent = getattr(meta, "recent_owner_name", None)
- if recent and recent != meta.primary_owner_name:
- ownership["recent_owner"] = recent
- ownership["recent_owner_pct"] = getattr(meta, "recent_owner_commit_pct", None)
- else:
- ownership["primary_owner"] = None
- ownership["owner_pct"] = None
- ownership["contributor_count"] = 0
- ownership["bus_factor"] = 0
- else:
- ownership["primary_owner"] = None
- ownership["owner_pct"] = None
- ownership["contributor_count"] = 0
- ownership["bus_factor"] = 0
- result_data["ownership"] = ownership
-
- # --- Last change ---
- if include is None or "last_change" in include:
- last_change: dict[str, Any] = {}
- git_path = file_path_for_git
- if target_type == "module" and page:
- git_path = page.target_path
- if git_path:
- res = await session.execute(
- select(GitMetadata).where(
- GitMetadata.repository_id == repo_id,
- GitMetadata.file_path == git_path,
- )
- )
- meta = res.scalar_one_or_none()
- if meta:
- last_change["date"] = (
- meta.last_commit_at.isoformat() if meta.last_commit_at else None
- )
- last_change["author"] = meta.primary_owner_name
- last_change["days_ago"] = meta.age_days
- else:
- last_change["date"] = None
- last_change["author"] = None
- last_change["days_ago"] = None
- else:
- last_change["date"] = None
- last_change["author"] = None
- last_change["days_ago"] = None
- result_data["last_change"] = last_change
-
- # --- Decisions ---
- if include is None or "decisions" in include:
- res = await session.execute(
- select(DecisionRecord).where(
- DecisionRecord.repository_id == repo_id,
- )
- )
- all_decisions = res.scalars().all()
- governing = []
- for d in all_decisions:
- affected_files = json.loads(d.affected_files_json)
- affected_modules = json.loads(d.affected_modules_json)
- if (
- target in affected_files
- or target in affected_modules
- or (file_path_for_git and file_path_for_git in affected_files)
- ):
- governing.append(
- {
- "id": d.id,
- "title": d.title,
- "status": d.status,
- "decision": d.decision,
- "rationale": d.rationale,
- "confidence": d.confidence,
- }
- )
- result_data["decisions"] = governing
-
- # --- Freshness ---
- if include is None or "freshness" in include:
- freshness: dict[str, Any] = {}
- if page:
- freshness["confidence_score"] = page.confidence
- freshness["freshness_status"] = page.freshness_status
- freshness["is_stale"] = (page.confidence or 1.0) < 0.6
- elif target_type == "symbol" and file_path_for_git:
- sym_page_id = f"file_page:{file_path_for_git}"
- sym_page = await session.get(Page, sym_page_id)
- if sym_page:
- freshness["confidence_score"] = sym_page.confidence
- freshness["freshness_status"] = sym_page.freshness_status
- freshness["is_stale"] = (sym_page.confidence or 1.0) < 0.6
- else:
- freshness["confidence_score"] = None
- freshness["freshness_status"] = None
- freshness["is_stale"] = None
- else:
- freshness["confidence_score"] = None
- freshness["freshness_status"] = None
- freshness["is_stale"] = None
- result_data["freshness"] = freshness
-
- # --- KG layer + tour context (Phase 9) ---
- if target_type == "file" and file_path_for_git:
- kg_layers = await get_kg_layers(session, repo_id)
- if kg_layers:
- for _l in kg_layers:
- _l._parsed_node_ids = json.loads(_l.node_ids_json) if _l.node_ids_json else []
- file_layer = _find_layer_for_file(file_path_for_git, kg_layers)
- if file_layer:
- edge_res = await session.execute(
- select(GraphEdge).where(
- GraphEdge.repository_id == repo_id,
- GraphEdge.target_node_id == file_path_for_git,
- GraphEdge.edge_type == "imports",
- )
- )
- incoming_edges = list(edge_res.scalars())
- result_data["architectural_layer"] = {
- "name": file_layer.name,
- "description": (file_layer.description or "")[:200],
- "role": _classify_file_role(file_path_for_git, file_layer, incoming_edges),
- }
-
- kg_tour = await get_kg_tour_steps(session, repo_id)
- if kg_tour:
- for _s in kg_tour:
- _s._parsed_node_ids = json.loads(_s.node_ids_json) if _s.node_ids_json else []
- file_tour_step = _find_tour_step_for_file(file_path_for_git, kg_tour)
- if file_tour_step:
- result_data["tour_context"] = {
- "step": file_tour_step.step_order,
- "title": file_tour_step.title,
- "why": (file_tour_step.description or "")[:200],
- }
-
- # --- Callers / Callees (replaces get_callers_callees) ---
- want_callers = bool(include and "callers" in include)
- want_callees = bool(include and "callees" in include)
- if want_callers or want_callees:
- await _resolve_call_graph(
- session,
- repository,
- target,
- target_type,
- result_data,
- want_callers=want_callers,
- want_callees=want_callees,
- )
-
- # --- Metrics (replaces get_graph_metrics) ---
- if include and "metrics" in include:
- await _resolve_metrics(session, repository, target, result_data)
-
- # --- Community (replaces get_community) ---
- if include and "community" in include:
- await _resolve_community(session, repository, target, result_data)
-
- # --- Code health (Phase 2) ---
- if include and "health" in include:
- await _resolve_health(session, repository, target, target_type, result_data)
-
- return result_data
-
-
-# ---------------------------------------------------------------------------
-# Merged tool helpers (source, callers/callees, metrics, community)
-# ---------------------------------------------------------------------------
-
-
-async def _resolve_call_graph(
- session: AsyncSession,
- repository: Repository,
- target: str,
- target_type: str | None,
- result_data: dict[str, Any],
- *,
- want_callers: bool = False,
- want_callees: bool = False,
-) -> None:
- """Resolve callers/callees for a symbol and attach to result_data."""
- repo_id = repository.id
- limit = 20
-
- # Resolve to a graph node (symbol)
- node = await get_graph_node(session, repo_id, target)
- if node is None and "::" in target:
- # Fuzzy: try bare name
- bare_name = target.split("::")[-1]
- res = await session.execute(
- select(GraphNode).where(
- GraphNode.repository_id == repo_id,
- GraphNode.node_type == "symbol",
- GraphNode.name == bare_name,
- )
- )
- rows = list(res.scalars().all())
- if rows:
- file_hint = target.split("::")[0]
- node = next((r for r in rows if r.file_path == file_hint), rows[0])
-
- if node is None or node.node_type != "symbol":
- # For file targets, return empty with explanation — callers/callees is symbol-only
- if want_callers:
- result_data["callers"] = []
- if want_callees:
- result_data["callees"] = []
- if node is not None and node.node_type != "symbol":
- result_data["_call_graph_note"] = (
- "callers/callees require a symbol target (function/class/method), "
- f"but '{target}' is a {node.node_type}. Pass a symbol name or file::Symbol."
- )
- return
-
- direction = "both"
- if want_callers and not want_callees:
- direction = "callers"
- elif want_callees and not want_callers:
- direction = "callees"
-
- edges = await get_graph_edges_for_node(
- session,
- repo_id,
- node.node_id,
- direction=direction,
- edge_types=["calls", "extends", "implements"],
- limit=limit,
- )
-
- # Hydrate other nodes
- other_ids = list(
- {e.source_node_id if e.target_node_id == node.node_id else e.target_node_id for e in edges}
- )
- node_map = await get_graph_nodes_by_ids(session, repo_id, other_ids)
-
- callers: list[dict[str, Any]] = []
- callees: list[dict[str, Any]] = []
-
- for e in edges:
- # Filter out low-confidence edges (false positives from Tier 3 global resolution)
- if (e.confidence or 0) < _MIN_CALL_CONFIDENCE:
- continue
-
- is_caller = e.target_node_id == node.node_id
- other_id = e.source_node_id if is_caller else e.target_node_id
- other_node = node_map.get(other_id)
-
- entry: dict[str, Any] = {
- "symbol_id": other_id,
- "name": other_node.name
- if other_node
- else (other_id.split("::")[-1] if "::" in other_id else other_id),
- "kind": other_node.kind if other_node else None,
- "file": other_node.file_path
- if other_node
- else (other_id.split("::")[0] if "::" in other_id else other_id),
- "confidence": e.confidence,
- "edge_type": e.edge_type,
- }
- if is_caller:
- callers.append(entry)
- else:
- callees.append(entry)
-
- # Sort by confidence DESC
- callers.sort(key=lambda x: -(x.get("confidence") or 0))
- callees.sort(key=lambda x: -(x.get("confidence") or 0))
-
- if want_callers:
- result_data["callers"] = callers
- if want_callees:
- result_data["callees"] = callees
-
-
-async def _resolve_metrics(
- session: AsyncSession,
- repository: Repository,
- target: str,
- result_data: dict[str, Any],
-) -> None:
- """Resolve graph importance metrics and attach to result_data["metrics"]."""
- repo_id = repository.id
-
- node = await get_graph_node(session, repo_id, target)
- if node is None:
- result_data["metrics"] = None
- return
-
- try:
- meta = json.loads(node.community_meta_json or "{}")
- except (json.JSONDecodeError, TypeError):
- meta = {}
-
- degrees = await get_node_degree_counts(session, repo_id, node.node_id)
-
- # Percentile computation against same-type peers
- all_nodes = await get_all_file_metrics(session, repo_id)
- pr_values = [n.pagerank for n in all_nodes if n.pagerank is not None]
- bt_values = [n.betweenness for n in all_nodes if n.betweenness is not None]
-
- def _pct(value: float, all_vals: list[float]) -> int:
- if not all_vals:
- return 0
- return round(100 * sum(1 for v in all_vals if v < value) / len(all_vals))
-
- result_data["metrics"] = {
- "pagerank": round(node.pagerank or 0.0, 6),
- "pagerank_percentile": _pct(node.pagerank or 0.0, pr_values),
- "betweenness": round(node.betweenness or 0.0, 6),
- "betweenness_percentile": _pct(node.betweenness or 0.0, bt_values),
- "in_degree": degrees["in_degree"],
- "out_degree": degrees["out_degree"],
- "community_id": node.community_id,
- "community_label": meta.get("label") or None,
- }
-
-
-async def _resolve_community(
- session: AsyncSession,
- repository: Repository,
- target: str,
- result_data: dict[str, Any],
-) -> None:
- """Resolve community membership and attach to result_data["community"]."""
- repo_id = repository.id
-
- node = await get_graph_node(session, repo_id, target)
- if node is None or node.community_id is None:
- result_data["community"] = None
- return
-
- try:
- meta = json.loads(node.community_meta_json or "{}")
- except (json.JSONDecodeError, TypeError):
- meta = {}
-
- label = meta.get("label") or f"cluster_{node.community_id}"
- cohesion = float(meta.get("cohesion", 0.0) or 0.0)
-
- # Get top members (cap at 10 for compact output)
- members = await get_community_members(session, repo_id, node.community_id, limit=10)
- member_paths = [m.node_id for m in members]
-
- # Neighboring communities (cap at 5)
- cross_edges = await get_cross_community_edges(session, repo_id, node.community_id)
- neighbors: list[dict[str, Any]] = []
- for ce in cross_edges[:5]:
- nid = ce["target_community_id"]
- nm = await get_community_members(session, repo_id, nid, limit=1)
- nlabel = ""
- if nm:
- try:
- nmeta = json.loads(nm[0].community_meta_json or "{}")
- nlabel = nmeta.get("label", "")
- except (json.JSONDecodeError, TypeError):
- pass
- neighbors.append(
- {
- "id": nid,
- "label": nlabel or f"cluster_{nid}",
- "cross_edges": ce["edge_count"],
- }
- )
-
- result_data["community"] = {
- "id": node.community_id,
- "label": label,
- "cohesion": round(cohesion, 3),
- "top_members": member_paths,
- "neighbors": neighbors,
- }
-
-
-async def _resolve_health(
- session: AsyncSession,
- repository: Repository,
- target: str,
- target_type: str,
- result_data: dict[str, Any],
-) -> None:
- """Attach per-file health metric + top 2 biomarkers + coverage row.
-
- Only meaningful for *file* targets. For symbol targets we resolve the
- enclosing file path via the already-computed ``file_path_for_git`` is
- not available here — we fall back to ``target`` when ``target_type``
- is ``"file"`` and otherwise inspect the target string for a
- ``"path::symbol"`` separator.
- """
- file_path: str | None
- if target_type == "file":
- file_path = target
- elif "::" in target:
- file_path = target.split("::", 1)[0]
- else:
- file_path = None
-
- if not file_path:
- result_data["health"] = None
- return
-
- repo_id = repository.id
- metric = (
- await session.execute(
- select(HealthFileMetric).where(
- HealthFileMetric.repository_id == repo_id,
- HealthFileMetric.file_path == file_path,
- )
- )
- ).scalar_one_or_none()
-
- if metric is None:
- result_data["health"] = None
- return
-
- findings_res = await session.execute(
- select(HealthFinding)
- .where(
- HealthFinding.repository_id == repo_id,
- HealthFinding.file_path == file_path,
- HealthFinding.status == "open",
- )
- .order_by(HealthFinding.health_impact.desc())
- .limit(2)
- )
- from repowise.core.analysis.health.suggestions import suggestion_for
-
- top_biomarkers = [
- {
- "biomarker_type": f.biomarker_type,
- "severity": f.severity,
- "function_name": f.function_name,
- "impact": round(f.health_impact, 2),
- "suggestion": suggestion_for(f.biomarker_type),
- }
- for f in findings_res.scalars().all()
- ]
-
- coverage_row = (
- await session.execute(
- select(CoverageFile).where(
- CoverageFile.repository_id == repo_id,
- CoverageFile.file_path == file_path,
- )
- )
- ).scalar_one_or_none()
-
- health: dict[str, Any] = {
- "score": round(metric.score, 2),
- "max_ccn": metric.max_ccn,
- "max_nesting": metric.max_nesting,
- "nloc": metric.nloc,
- "has_test_file": metric.has_test_file,
- "module": metric.module,
- "duplication_pct": metric.duplication_pct,
- "top_biomarkers": top_biomarkers,
- }
- if coverage_row is not None:
- health["coverage"] = {
- "source_format": coverage_row.source_format,
- "line_coverage_pct": coverage_row.line_coverage_pct,
- "branch_coverage_pct": coverage_row.branch_coverage_pct,
- "total_coverable_lines": coverage_row.total_coverable_lines,
- }
- elif metric.line_coverage_pct is not None:
- health["coverage"] = {
- "line_coverage_pct": metric.line_coverage_pct,
- "branch_coverage_pct": metric.branch_coverage_pct,
- }
- result_data["health"] = health
-
-
-def _find_layer_for_file(path: str, layers: list) -> Any | None:
- for layer in layers:
- node_ids = getattr(layer, "_parsed_node_ids", None)
- if node_ids is None:
- node_ids = json.loads(layer.node_ids_json) if layer.node_ids_json else []
- if f"file:{path}" in node_ids or path in node_ids:
- return layer
- return None
-
-
-def _find_tour_step_for_file(path: str, steps: list) -> Any | None:
- for step in steps:
- node_ids = getattr(step, "_parsed_node_ids", None)
- if node_ids is None:
- node_ids = json.loads(step.node_ids_json) if step.node_ids_json else []
- if f"file:{path}" in node_ids or path in node_ids:
- return step
- return None
-
-
-def _classify_file_role(path: str, layer: Any, incoming_edges: list) -> str:
- raw = getattr(layer, "_parsed_node_ids", None)
- if raw is None:
- raw = json.loads(layer.node_ids_json) if layer.node_ids_json else []
- node_ids = set(raw)
- cross_layer = [
- e
- for e in incoming_edges
- if f"file:{e.source_node_id}" not in node_ids and e.source_node_id not in node_ids
- ]
- if cross_layer:
- return "edge_connector"
- if not incoming_edges:
- return "entry_point"
- return "internal"
-
-
-def _estimate_tokens(obj: Any) -> int:
- """Cheap upper-bound token estimate for an arbitrary JSON-serialisable object.
-
- Serialises to compact JSON (the wire format the MCP layer eventually emits)
- and divides by ``_CHARS_PER_TOKEN``. We use the serialised form — not just
- raw text fields — because structural JSON overhead (quotes, braces, field
- names) is non-trivial and is what the downstream tokenizer actually sees.
- """
- return len(json.dumps(obj, separators=(",", ":"), default=str)) // _CHARS_PER_TOKEN
-
-
-# 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.
-_HEAVY_DOC_FIELDS: tuple[str, ...] = ("content_md", "documentation", "file_summary")
-
-
-def _symbol_priority(sym: dict[str, Any], query_terms: set[str]) -> tuple[int, int, int]:
- """Return a sort key (higher = keep) for a symbol within a target.
-
- Priority order (language-agnostic — no Python-specific heuristics):
- 1. Exact name match against any user query term.
- 2. Substring / case-insensitive match against query terms.
- 3. Kind rank: classes/types outrank functions/methods which outrank the
- rest. This mirrors navigational usefulness across Python, TS, Go,
- Rust, C++, etc. where a type anchors a module more than a helper fn.
- 4. PageRank / centrality if present on the dict (forward-compatible —
- ``get_context`` doesn't currently populate it but ``_resolve_one_target``
- may in the future).
- """
- name = (sym.get("name") or "").lower()
- exact = 1 if name and name in query_terms else 0
- fuzzy = 1 if any(t and t in name for t in query_terms) else 0
- kind = (sym.get("kind") or "").lower()
- kind_rank = {
- "class": 3,
- "interface": 3,
- "struct": 3,
- "trait": 3,
- "type": 3,
- "enum": 3,
- "function": 2,
- "method": 2,
- }.get(kind, 1)
- centrality = int((sym.get("pagerank") or sym.get("centrality") or 0) * 1000)
- return (exact * 10 + fuzzy * 5 + kind_rank, centrality, -len(json.dumps(sym, default=str)))
-
-
-def _query_terms_for(target: str) -> set[str]:
- """Derive cheap query terms from a target string for symbol prioritisation.
-
- ``get_context`` has no explicit query argument, so we fall back to the
- target identifier itself — the tail of a file path, or the raw symbol name.
- This is deliberately coarse: it just nudges symbol retention toward the
- thing the caller asked about.
- """
- tail = target.rsplit("/", 1)[-1].lower()
- # Strip common extension if present (language-agnostic: split once on '.').
- if "." in tail:
- tail = tail.rsplit(".", 1)[0]
- return {t for t in (tail, target.lower()) if t}
-
-
-def _truncate_to_budget(
- result: dict[str, Any],
- char_budget: int = _CHAR_BUDGET,
-) -> dict[str, Any]:
- """Cap the ``get_context`` response at roughly ``_TOKEN_BUDGET`` tokens.
-
- Strategy (applied in order, stopping as soon as the budget is met):
-
- 1. **Strip heavy optional doc fields** (``content_md``, ``documentation``,
- ``file_summary``) from each target. These are 1–2k tokens apiece and
- duplicate information the agent can re-request via ``full_doc``.
- 2. **Shrink symbol lists within each target**, keeping the highest-priority
- symbols per ``_symbol_priority``. This preserves the navigational index
- (names, signatures, line numbers) while dropping bulk docstrings.
- 3. **Drop whole targets** from the tail of the list. Per spec we prefer
- keeping fewer full-fidelity targets over many stubs, so once symbols
- can't shrink further we evict entire targets rather than gutting them.
-
- Adds ``truncated: bool``, ``dropped_targets: list[str]``, and
- ``dropped_symbols: dict[target, list[name]]`` top-level fields — additive
- only, existing callers are unaffected.
-
- Edge cases:
- * Empty ``targets`` → returns unchanged with ``truncated=False``.
- * A single target whose symbol list alone busts the budget → we reduce
- symbols down to 1 and accept the overshoot rather than returning an
- empty response. The ``truncated`` flag still fires.
- * Targets that carry an ``error`` field (not-found) are cheap and are
- preserved unless literally nothing else fits.
- """
- result.setdefault("truncated", False)
- result.setdefault("dropped_targets", [])
- result.setdefault("dropped_symbols", {})
-
- targets: dict[str, Any] = result.get("targets") or {}
- if not targets:
- return result
-
- def _size() -> int:
- return len(json.dumps(result, separators=(",", ":"), default=str))
-
- if _size() <= char_budget:
- return result
-
- # Stage 1: strip heavy optional doc fields across all targets.
- for name, tgt in targets.items():
- docs = tgt.get("docs") if isinstance(tgt, dict) else None
- if not isinstance(docs, dict):
- continue
- for field in _HEAVY_DOC_FIELDS:
- if field in docs:
- docs.pop(field, None)
- result["truncated"] = True
- if _size() <= char_budget:
- return result
-
- # Stage 2: prioritise symbols within each target. We iterate from the
- # largest target down so the biggest offenders shrink first.
- def _target_cost(item: tuple[str, Any]) -> int:
- return len(json.dumps(item[1], default=str))
-
- for tgt_name, tgt in sorted(targets.items(), key=_target_cost, reverse=True):
- docs = tgt.get("docs") if isinstance(tgt, dict) else None
- if not isinstance(docs, dict):
- continue
- symbols = docs.get("symbols")
- if not isinstance(symbols, list) or not symbols:
- continue
- query_terms = _query_terms_for(tgt_name)
- ordered = sorted(symbols, key=lambda s: _symbol_priority(s, query_terms), reverse=True)
- kept: list[dict[str, Any]] = []
- dropped: list[str] = []
- # Add symbols one at a time from highest priority until we hit the cap.
- for sym in ordered:
- docs["symbols"] = kept + [sym]
- if _size() <= char_budget:
- kept.append(sym)
- else:
- dropped.append(sym.get("name") or "<anonymous>")
- if 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):
- head["docstring"] = head["docstring"][:200]
- kept = [head]
- dropped = [s.get("name") or "<anonymous>" for s in ordered[1:]]
- docs["symbols"] = kept
- if dropped:
- result["dropped_symbols"][tgt_name] = dropped
- result["truncated"] = True
- if _size() <= char_budget:
- return result
-
- # Stage 3: drop whole targets, largest first, until we fit. Prefer to keep
- # error-only targets (they're tiny and signal "not found" to the caller).
- def _evictable_order() -> list[str]:
- items = list(targets.items())
- items.sort(
- key=lambda kv: (
- 0 if isinstance(kv[1], dict) and "error" in kv[1] else 1,
- len(json.dumps(kv[1], default=str)),
- ),
- reverse=True,
- )
- return [k for k, _ in items]
-
- for name in _evictable_order():
- if len(targets) <= 1:
- break
- targets.pop(name, None)
- result["dropped_targets"].append(name)
- result["truncated"] = True
- if _size() <= char_budget:
- break
-
- if result["truncated"]:
- logger.info(
- "get_context truncated to budget",
- extra={
- "char_budget": char_budget,
- "token_budget": _TOKEN_BUDGET,
- "final_chars": _size(),
- "dropped_targets": result["dropped_targets"],
- "dropped_symbol_counts": {k: len(v) for k, v in result["dropped_symbols"].items()},
- },
- )
- return result
-
-
-async def get_context(
- targets: list[str],
- include: list[str] | None = None,
- compact: bool = True,
- repo: str | None = None,
-) -> dict:
- """Triage card for files / modules / symbols — relationships, not source bytes.
-
- Returns a compact card the agent can use to decide its next move: title,
- summary, signatures, hotspot bit, top callers, and pointers (decision_record
- titles, symbol_ids) into the deeper tools. For the actual source body of a
- symbol, call ``get_symbol("path/to/file.py::Name")`` — it is cheaper than
- Read and returns bounded bytes with exact line numbers.
-
- Batch multiple targets in one call. In workspace mode responses are
- auto-enriched with cross-repo co-change partners and API contract links.
-
- Include options (everything outside defaults is opt-in):
- - "full_doc": full wiki markdown content for the target
- - "ownership": primary owner, bus factor, contributor count
- - "last_change":last commit date and author
- - "callers": who calls this symbol (symbol targets only)
- - "callees": what this symbol calls (symbol targets only)
- - "metrics": PageRank, betweenness centrality, percentile ranks
- - "community": architectural community membership + neighbors
- - "decisions": full decision records (default returns titles only)
-
- Example: get_context(["src/auth/service.py", "src/auth/middleware.py"])
- Example: get_context(["src/auth/service.py::verify_token"], include=["callers"])
-
- Args:
- targets: file paths, module paths, or qualified symbol IDs.
- include: list of optional data blocks (defaults are always returned).
- compact: default True (signatures only). False adds structure+imports+docstrings.
- repo: usually omitted.
- """
- if repo == "all":
- return _unsupported_repo_all("get_context")
- ctx = await _resolve_repo_context(repo)
-
- # Default to docs + freshness when include is omitted. Freshness is
- # critical for the agent to detect stale index data. The other blocks
- # (ownership/last_change/decisions) are 200–500 bytes each and bloat
- # every subsequent agent turn via cache replay. Callers that want them
- # must pass include explicitly.
- include_set = set(include) if include else {"docs", "freshness"}
-
- import time as _time
-
- _t0 = _time.perf_counter()
- async with get_session(ctx.session_factory) as session:
- repository = await _get_repo(session)
-
- results = await asyncio.gather(
- *[
- _resolve_one_target(
- session,
- repository,
- t,
- include_set,
- compact,
- )
- for t in targets
- ]
- )
-
- response: dict[str, Any] = {
- "targets": {r["target"]: r for r in results},
- "_meta": _build_meta(
- timing_ms=(_time.perf_counter() - _t0) * 1000,
- hint=_context_hint(targets, compact, include_set),
- repository=repository,
- ),
- }
-
- # Cross-repo enrichment (Phase 3 + 4)
- from repowise.server.mcp_server._helpers import _is_workspace_mode
-
- enricher = _state._cross_repo_enricher
- if enricher is not None and enricher.has_data and _is_workspace_mode():
- for target_key, target_data in response["targets"].items():
- cross_repo: dict[str, Any] = {}
-
- partners = enricher.get_cross_repo_partners(ctx.alias, target_key)
- if partners:
- cross_repo["co_changes_with"] = [
- {"repo": p["repo"], "file": p["file"], "strength": p["strength"]}
- for p in partners[:5]
- ]
-
- # Contract links (Phase 4)
- if enricher.has_contract_data:
- provider_links = enricher.get_contract_links_as_provider(ctx.alias, target_key)
- consumer_links = enricher.get_contract_links_as_consumer(ctx.alias, target_key)
- if provider_links or consumer_links:
- contracts: dict[str, Any] = {}
- if provider_links:
- contracts["consumers"] = [
- {
- "consumer_repo": lk["consumer_repo"],
- "contract_id": lk["contract_id"],
- "type": lk["contract_type"],
- }
- for lk in provider_links[:5]
- ]
- if consumer_links:
- contracts["providers"] = [
- {
- "provider_repo": lk["provider_repo"],
- "contract_id": lk["contract_id"],
- "type": lk["contract_type"],
- }
- for lk in consumer_links[:5]
- ]
- cross_repo["contracts"] = contracts
-
- if cross_repo:
- target_data["cross_repo"] = cross_repo
-
- # Enforce the global token cap. See ``_truncate_to_budget`` for strategy.
- return _truncate_to_budget(response)
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/__init__.py b/packages/server/src/repowise/server/mcp_server/tool_context/__init__.py
new file mode 100644
index 000000000..1f68fe9cb
--- /dev/null
+++ b/packages/server/src/repowise/server/mcp_server/tool_context/__init__.py
@@ -0,0 +1,26 @@
+"""get_context MCP tool — relationships and triage signals.
+
+Façade: the tool used to be a single 1213-line ``tool_context.py``. It is now
+a package (orchestrator + targets / enrichment / kg / truncation). Importers
+keep working unchanged — ``from ...tool_context import get_context`` resolves,
+importing the package registers the tool via ``@mcp.tool()``, and the
+truncation helpers (used by tests) remain importable from the package root.
+"""
+
+from __future__ import annotations
+
+from repowise.server.mcp_server.tool_context.context import get_context
+from repowise.server.mcp_server.tool_context.truncation import (
+ _CHAR_BUDGET,
+ _TOKEN_BUDGET,
+ _estimate_tokens,
+ _truncate_to_budget,
+)
+
+__all__ = [
+ "_CHAR_BUDGET",
+ "_TOKEN_BUDGET",
+ "_estimate_tokens",
+ "_truncate_to_budget",
+ "get_context",
+]
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
new file mode 100644
index 000000000..cd8965c90
--- /dev/null
+++ b/packages/server/src/repowise/server/mcp_server/tool_context/context.py
@@ -0,0 +1,164 @@
+"""MCP Tool: get_context — relationships and triage signals for files / modules / symbols.
+
+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.
+
+Optional ``include`` parameter widens the response:
+ - include=["full_doc"] → full wiki markdown content
+ - include=["callers"] → who calls this symbol (symbol targets only)
+ - include=["callees"] → what this symbol calls (symbol targets only)
+ - include=["ownership"] → primary owner, bus factor, contributor count
+ - include=["last_change"]→ last commit date and author
+ - include=["metrics"] → PageRank, betweenness, percentile ranks
+ - include=["community"] → community membership + neighbors
+ - include=["decisions"] → full decision records (default returns titles only)
+
+This module is the orchestrator; single-target resolution lives in
+``targets`` and the budget cap in ``truncation``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from repowise.core.persistence.database import get_session
+from repowise.core.registry import mcp_tool_registry as mcp
+from repowise.server.mcp_server import _state
+from repowise.server.mcp_server._helpers import (
+ _get_repo,
+ _resolve_repo_context,
+ _unsupported_repo_all,
+)
+from repowise.server.mcp_server._meta import build_meta as _build_meta
+from repowise.server.mcp_server._meta import context_hint as _context_hint
+from repowise.server.mcp_server.tool_context.targets import _resolve_one_target
+from repowise.server.mcp_server.tool_context.truncation import _truncate_to_budget
+
+
+async def get_context(
+ targets: list[str],
+ include: list[str] | None = None,
+ compact: bool = True,
+ repo: str | None = None,
+) -> dict:
+ """Triage card for files / modules / symbols — relationships, not source bytes.
+
+ Returns a compact card the agent can use to decide its next move: title,
+ summary, signatures, hotspot bit, top callers, and pointers (decision_record
+ titles, symbol_ids) into the deeper tools. For the actual source body of a
+ symbol, call ``get_symbol("path/to/file.py::Name")`` — it is cheaper than
+ Read and returns bounded bytes with exact line numbers.
+
+ Batch multiple targets in one call. In workspace mode responses are
+ auto-enriched with cross-repo co-change partners and API contract links.
+
+ Include options (everything outside defaults is opt-in):
+ - "full_doc": full wiki markdown content for the target
+ - "ownership": primary owner, bus factor, contributor count
+ - "last_change":last commit date and author
+ - "callers": who calls this symbol (symbol targets only)
+ - "callees": what this symbol calls (symbol targets only)
+ - "metrics": PageRank, betweenness centrality, percentile ranks
+ - "community": architectural community membership + neighbors
+ - "decisions": full decision records (default returns titles only)
+
+ Example: get_context(["src/auth/service.py", "src/auth/middleware.py"])
+ Example: get_context(["src/auth/service.py::verify_token"], include=["callers"])
+
+ Args:
+ targets: file paths, module paths, or qualified symbol IDs.
+ include: list of optional data blocks (defaults are always returned).
+ compact: default True (signatures only). False adds structure+imports+docstrings.
+ repo: usually omitted.
+ """
+ if repo == "all":
+ return _unsupported_repo_all("get_context")
+ ctx = await _resolve_repo_context(repo)
+
+ # Default to docs + freshness when include is omitted. Freshness is
+ # critical for the agent to detect stale index data. The other blocks
+ # (ownership/last_change/decisions) are 200–500 bytes each and bloat
+ # every subsequent agent turn via cache replay. Callers that want them
+ # must pass include explicitly.
+ include_set = set(include) if include else {"docs", "freshness"}
+
+ import time as _time
+
+ _t0 = _time.perf_counter()
+ async with get_session(ctx.session_factory) as session:
+ repository = await _get_repo(session)
+
+ results = await asyncio.gather(
+ *[
+ _resolve_one_target(
+ session,
+ repository,
+ t,
+ include_set,
+ compact,
+ )
+ for t in targets
+ ]
+ )
+
+ response: dict[str, Any] = {
+ "targets": {r["target"]: r for r in results},
+ "_meta": _build_meta(
+ timing_ms=(_time.perf_counter() - _t0) * 1000,
+ hint=_context_hint(targets, compact, include_set),
+ repository=repository,
+ ),
+ }
+
+ # Cross-repo enrichment (Phase 3 + 4)
+ from repowise.server.mcp_server._helpers import _is_workspace_mode
+
+ enricher = _state._cross_repo_enricher
+ if enricher is not None and enricher.has_data and _is_workspace_mode():
+ for target_key, target_data in response["targets"].items():
+ cross_repo: dict[str, Any] = {}
+
+ partners = enricher.get_cross_repo_partners(ctx.alias, target_key)
+ if partners:
+ cross_repo["co_changes_with"] = [
+ {"repo": p["repo"], "file": p["file"], "strength": p["strength"]}
+ for p in partners[:5]
+ ]
+
+ # Contract links (Phase 4)
+ if enricher.has_contract_data:
+ provider_links = enricher.get_contract_links_as_provider(ctx.alias, target_key)
+ consumer_links = enricher.get_contract_links_as_consumer(ctx.alias, target_key)
+ if provider_links or consumer_links:
+ contracts: dict[str, Any] = {}
+ if provider_links:
+ contracts["consumers"] = [
+ {
+ "consumer_repo": lk["consumer_repo"],
+ "contract_id": lk["contract_id"],
+ "type": lk["contract_type"],
+ }
+ for lk in provider_links[:5]
+ ]
+ if consumer_links:
+ contracts["providers"] = [
+ {
+ "provider_repo": lk["provider_repo"],
+ "contract_id": lk["contract_id"],
+ "type": lk["contract_type"],
+ }
+ for lk in consumer_links[:5]
+ ]
+ cross_repo["contracts"] = contracts
+
+ if cross_repo:
+ target_data["cross_repo"] = cross_repo
+
+ # Enforce the global token cap. See ``_truncate_to_budget`` for strategy.
+ return _truncate_to_budget(response)
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py b/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py
new file mode 100644
index 000000000..cf22f2f72
--- /dev/null
+++ b/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py
@@ -0,0 +1,336 @@
+"""Optional enrichment blocks for get_context.
+
+Each helper resolves one ``include=`` block (callers/callees, metrics,
+community, health) and attaches it to ``result_data`` in place. They are split
+out of the main target resolver so the orchestrator and the resolver read as
+dispatch rather than one long body.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from repowise.core.persistence.crud import (
+ get_all_file_metrics,
+ get_community_members,
+ get_cross_community_edges,
+ get_graph_edges_for_node,
+ get_graph_node,
+ get_graph_nodes_by_ids,
+ get_node_degree_counts,
+)
+from repowise.core.persistence.models import (
+ CoverageFile,
+ GraphNode,
+ HealthFileMetric,
+ HealthFinding,
+ Repository,
+)
+
+# Minimum confidence for call edges to filter false positives
+_MIN_CALL_CONFIDENCE = 0.7
+
+
+async def _resolve_call_graph(
+ session: AsyncSession,
+ repository: Repository,
+ target: str,
+ target_type: str | None,
+ result_data: dict[str, Any],
+ *,
+ want_callers: bool = False,
+ want_callees: bool = False,
+) -> None:
+ """Resolve callers/callees for a symbol and attach to result_data."""
+ repo_id = repository.id
+ limit = 20
+
+ # Resolve to a graph node (symbol)
+ node = await get_graph_node(session, repo_id, target)
+ if node is None and "::" in target:
+ # Fuzzy: try bare name
+ bare_name = target.split("::")[-1]
+ res = await session.execute(
+ select(GraphNode).where(
+ GraphNode.repository_id == repo_id,
+ GraphNode.node_type == "symbol",
+ GraphNode.name == bare_name,
+ )
+ )
+ rows = list(res.scalars().all())
+ if rows:
+ file_hint = target.split("::")[0]
+ node = next((r for r in rows if r.file_path == file_hint), rows[0])
+
+ if node is None or node.node_type != "symbol":
+ # For file targets, return empty with explanation — callers/callees is symbol-only
+ if want_callers:
+ result_data["callers"] = []
+ if want_callees:
+ result_data["callees"] = []
+ if node is not None and node.node_type != "symbol":
+ result_data["_call_graph_note"] = (
+ "callers/callees require a symbol target (function/class/method), "
+ f"but '{target}' is a {node.node_type}. Pass a symbol name or file::Symbol."
+ )
+ return
+
+ direction = "both"
+ if want_callers and not want_callees:
+ direction = "callers"
+ elif want_callees and not want_callers:
+ direction = "callees"
+
+ edges = await get_graph_edges_for_node(
+ session,
+ repo_id,
+ node.node_id,
+ direction=direction,
+ edge_types=["calls", "extends", "implements"],
+ limit=limit,
+ )
+
+ # Hydrate other nodes
+ other_ids = list(
+ {e.source_node_id if e.target_node_id == node.node_id else e.target_node_id for e in edges}
+ )
+ node_map = await get_graph_nodes_by_ids(session, repo_id, other_ids)
+
+ callers: list[dict[str, Any]] = []
+ callees: list[dict[str, Any]] = []
+
+ for e in edges:
+ # Filter out low-confidence edges (false positives from Tier 3 global resolution)
+ if (e.confidence or 0) < _MIN_CALL_CONFIDENCE:
+ continue
+
+ is_caller = e.target_node_id == node.node_id
+ other_id = e.source_node_id if is_caller else e.target_node_id
+ other_node = node_map.get(other_id)
+
+ entry: dict[str, Any] = {
+ "symbol_id": other_id,
+ "name": other_node.name
+ if other_node
+ else (other_id.split("::")[-1] if "::" in other_id else other_id),
+ "kind": other_node.kind if other_node else None,
+ "file": other_node.file_path
+ if other_node
+ else (other_id.split("::")[0] if "::" in other_id else other_id),
+ "confidence": e.confidence,
+ "edge_type": e.edge_type,
+ }
+ if is_caller:
+ callers.append(entry)
+ else:
+ callees.append(entry)
+
+ # Sort by confidence DESC
+ callers.sort(key=lambda x: -(x.get("confidence") or 0))
+ callees.sort(key=lambda x: -(x.get("confidence") or 0))
+
+ if want_callers:
+ result_data["callers"] = callers
+ if want_callees:
+ result_data["callees"] = callees
+
+
+async def _resolve_metrics(
+ session: AsyncSession,
+ repository: Repository,
+ target: str,
+ result_data: dict[str, Any],
+) -> None:
+ """Resolve graph importance metrics and attach to result_data["metrics"]."""
+ repo_id = repository.id
+
+ node = await get_graph_node(session, repo_id, target)
+ if node is None:
+ result_data["metrics"] = None
+ return
+
+ try:
+ meta = json.loads(node.community_meta_json or "{}")
+ except (json.JSONDecodeError, TypeError):
+ meta = {}
+
+ degrees = await get_node_degree_counts(session, repo_id, node.node_id)
+
+ # Percentile computation against same-type peers
+ all_nodes = await get_all_file_metrics(session, repo_id)
+ pr_values = [n.pagerank for n in all_nodes if n.pagerank is not None]
+ bt_values = [n.betweenness for n in all_nodes if n.betweenness is not None]
+
+ def _pct(value: float, all_vals: list[float]) -> int:
+ if not all_vals:
+ return 0
+ return round(100 * sum(1 for v in all_vals if v < value) / len(all_vals))
+
+ result_data["metrics"] = {
+ "pagerank": round(node.pagerank or 0.0, 6),
+ "pagerank_percentile": _pct(node.pagerank or 0.0, pr_values),
+ "betweenness": round(node.betweenness or 0.0, 6),
+ "betweenness_percentile": _pct(node.betweenness or 0.0, bt_values),
+ "in_degree": degrees["in_degree"],
+ "out_degree": degrees["out_degree"],
+ "community_id": node.community_id,
+ "community_label": meta.get("label") or None,
+ }
+
+
+async def _resolve_community(
+ session: AsyncSession,
+ repository: Repository,
+ target: str,
+ result_data: dict[str, Any],
+) -> None:
+ """Resolve community membership and attach to result_data["community"]."""
+ repo_id = repository.id
+
+ node = await get_graph_node(session, repo_id, target)
+ if node is None or node.community_id is None:
+ result_data["community"] = None
+ return
+
+ try:
+ meta = json.loads(node.community_meta_json or "{}")
+ except (json.JSONDecodeError, TypeError):
+ meta = {}
+
+ label = meta.get("label") or f"cluster_{node.community_id}"
+ cohesion = float(meta.get("cohesion", 0.0) or 0.0)
+
+ # Get top members (cap at 10 for compact output)
+ members = await get_community_members(session, repo_id, node.community_id, limit=10)
+ member_paths = [m.node_id for m in members]
+
+ # Neighboring communities (cap at 5)
+ cross_edges = await get_cross_community_edges(session, repo_id, node.community_id)
+ neighbors: list[dict[str, Any]] = []
+ for ce in cross_edges[:5]:
+ nid = ce["target_community_id"]
+ nm = await get_community_members(session, repo_id, nid, limit=1)
+ nlabel = ""
+ if nm:
+ try:
+ nmeta = json.loads(nm[0].community_meta_json or "{}")
+ nlabel = nmeta.get("label", "")
+ except (json.JSONDecodeError, TypeError):
+ pass
+ neighbors.append(
+ {
+ "id": nid,
+ "label": nlabel or f"cluster_{nid}",
+ "cross_edges": ce["edge_count"],
+ }
+ )
+
+ result_data["community"] = {
+ "id": node.community_id,
+ "label": label,
+ "cohesion": round(cohesion, 3),
+ "top_members": member_paths,
+ "neighbors": neighbors,
+ }
+
+
+async def _resolve_health(
+ session: AsyncSession,
+ repository: Repository,
+ target: str,
+ target_type: str,
+ result_data: dict[str, Any],
+) -> None:
+ """Attach per-file health metric + top 2 biomarkers + coverage row.
+
+ Only meaningful for *file* targets. For symbol targets we resolve the
+ enclosing file path via the already-computed ``file_path_for_git`` is
+ not available here — we fall back to ``target`` when ``target_type``
+ is ``"file"`` and otherwise inspect the target string for a
+ ``"path::symbol"`` separator.
+ """
+ file_path: str | None
+ if target_type == "file":
+ file_path = target
+ elif "::" in target:
+ file_path = target.split("::", 1)[0]
+ else:
+ file_path = None
+
+ if not file_path:
+ result_data["health"] = None
+ return
+
+ repo_id = repository.id
+ metric = (
+ await session.execute(
+ select(HealthFileMetric).where(
+ HealthFileMetric.repository_id == repo_id,
+ HealthFileMetric.file_path == file_path,
+ )
+ )
+ ).scalar_one_or_none()
+
+ if metric is None:
+ result_data["health"] = None
+ return
+
+ findings_res = await session.execute(
+ select(HealthFinding)
+ .where(
+ HealthFinding.repository_id == repo_id,
+ HealthFinding.file_path == file_path,
+ HealthFinding.status == "open",
+ )
+ .order_by(HealthFinding.health_impact.desc())
+ .limit(2)
+ )
+ from repowise.core.analysis.health.suggestions import suggestion_for
+
+ top_biomarkers = [
+ {
+ "biomarker_type": f.biomarker_type,
+ "severity": f.severity,
+ "function_name": f.function_name,
+ "impact": round(f.health_impact, 2),
+ "suggestion": suggestion_for(f.biomarker_type),
+ }
+ for f in findings_res.scalars().all()
+ ]
+
+ coverage_row = (
+ await session.execute(
+ select(CoverageFile).where(
+ CoverageFile.repository_id == repo_id,
+ CoverageFile.file_path == file_path,
+ )
+ )
+ ).scalar_one_or_none()
+
+ health: dict[str, Any] = {
+ "score": round(metric.score, 2),
+ "max_ccn": metric.max_ccn,
+ "max_nesting": metric.max_nesting,
+ "nloc": metric.nloc,
+ "has_test_file": metric.has_test_file,
+ "module": metric.module,
+ "duplication_pct": metric.duplication_pct,
+ "top_biomarkers": top_biomarkers,
+ }
+ if coverage_row is not None:
+ health["coverage"] = {
+ "source_format": coverage_row.source_format,
+ "line_coverage_pct": coverage_row.line_coverage_pct,
+ "branch_coverage_pct": coverage_row.branch_coverage_pct,
+ "total_coverable_lines": coverage_row.total_coverable_lines,
+ }
+ elif metric.line_coverage_pct is not None:
+ health["coverage"] = {
+ "line_coverage_pct": metric.line_coverage_pct,
+ "branch_coverage_pct": metric.branch_coverage_pct,
+ }
+ result_data["health"] = health
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/kg.py b/packages/server/src/repowise/server/mcp_server/tool_context/kg.py
new file mode 100644
index 000000000..64097635e
--- /dev/null
+++ b/packages/server/src/repowise/server/mcp_server/tool_context/kg.py
@@ -0,0 +1,43 @@
+"""Knowledge-graph layer / tour / role helpers for get_context."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def _find_layer_for_file(path: str, layers: list) -> Any | None:
+ for layer in layers:
+ node_ids = getattr(layer, "_parsed_node_ids", None)
+ if node_ids is None:
+ node_ids = json.loads(layer.node_ids_json) if layer.node_ids_json else []
+ if f"file:{path}" in node_ids or path in node_ids:
+ return layer
+ return None
+
+
+def _find_tour_step_for_file(path: str, steps: list) -> Any | None:
+ for step in steps:
+ node_ids = getattr(step, "_parsed_node_ids", None)
+ if node_ids is None:
+ node_ids = json.loads(step.node_ids_json) if step.node_ids_json else []
+ if f"file:{path}" in node_ids or path in node_ids:
+ return step
+ return None
+
+
+def _classify_file_role(path: str, layer: Any, incoming_edges: list) -> str:
+ raw = getattr(layer, "_parsed_node_ids", None)
+ if raw is None:
+ raw = json.loads(layer.node_ids_json) if layer.node_ids_json else []
+ node_ids = set(raw)
+ cross_layer = [
+ e
+ for e in incoming_edges
+ if f"file:{e.source_node_id}" not in node_ids and e.source_node_id not in node_ids
+ ]
+ if cross_layer:
+ return "edge_connector"
+ if not incoming_edges:
+ return "entry_point"
+ return "internal"
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
new file mode 100644
index 000000000..10153d353
--- /dev/null
+++ b/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
@@ -0,0 +1,633 @@
+"""Single-target resolution for get_context.
+
+``_resolve_one_target`` walks the file → module → symbol → fallback ladder for
+one target and assembles its triage card (docs, triage signals, ownership,
+last_change, decisions, freshness, KG layer/tour, and the opt-in enrichment
+blocks delegated to ``enrichment``).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from repowise.core.persistence.crud import get_kg_layers, get_kg_tour_steps
+from repowise.core.persistence.decision_graph import get_governing_decisions
+from repowise.core.persistence.models import (
+ DecisionRecord,
+ GitMetadata,
+ GraphEdge,
+ GraphNode,
+ Page,
+ Repository,
+ WikiSymbol,
+)
+from repowise.server.mcp_server.tool_context.enrichment import (
+ _resolve_call_graph,
+ _resolve_community,
+ _resolve_health,
+ _resolve_metrics,
+)
+from repowise.server.mcp_server.tool_context.kg import (
+ _classify_file_role,
+ _find_layer_for_file,
+ _find_tour_step_for_file,
+)
+
+
+def _synthesize_structural_summary(file_path: str, classes: list[str], functions: list[str]) -> str:
+ """Build a deterministic 1-line summary when no LLM-generated summary exists.
+
+ Used in --index-only mode (no wiki pages) and as a fallback when an LLM
+ page predates the summary column. Always returns a non-empty string so the
+ agent never sees a missing field.
+ """
+ name = file_path.rsplit("/", 1)[-1]
+ parts: list[str] = []
+ if classes:
+ head = ", ".join(classes[:3])
+ more = f" (+{len(classes) - 3} more)" if len(classes) > 3 else ""
+ parts.append(f"defines {head}{more}")
+ if functions:
+ head = ", ".join(functions[:3])
+ more = f" (+{len(functions) - 3} more)" if len(functions) > 3 else ""
+ parts.append(f"function{'s' if len(functions) > 1 else ''} {head}{more}")
+ if not parts:
+ return f"{name}: empty or non-symbol file"
+ return f"{name}: " + "; ".join(parts) + "."
+
+
+async def _resolve_one_target(
+ session: AsyncSession,
+ repository: Repository,
+ target: str,
+ include: set[str] | None,
+ compact: bool = False,
+) -> dict:
+ """Resolve a single target and return its full context."""
+ repo_id = repository.id
+ result_data: dict[str, Any] = {}
+
+ # --- Determine target type ---
+ # 1. Try file page (most common)
+ page_id = f"file_page:{target}"
+ page = await session.get(Page, page_id)
+ target_type = None
+ file_path_for_git: str | None = None
+
+ if page and page.repository_id == repo_id:
+ target_type = "file"
+ file_path_for_git = target
+ else:
+ # 1b. Normalise directory targets: strip trailing slash and try module
+ clean_target = target.rstrip("/")
+ # 2. Try module page (exact, then cleaned, then partial)
+ res = await session.execute(
+ select(Page).where(
+ Page.repository_id == repo_id,
+ Page.page_type == "module_page",
+ Page.target_path == target,
+ )
+ )
+ page = res.scalar_one_or_none()
+ if page is None and clean_target != target:
+ res = await session.execute(
+ select(Page).where(
+ Page.repository_id == repo_id,
+ Page.page_type == "module_page",
+ Page.target_path == clean_target,
+ )
+ )
+ page = res.scalar_one_or_none()
+ if page is None:
+ # Partial match fallback for modules
+ res = await session.execute(
+ select(Page).where(
+ Page.repository_id == repo_id,
+ Page.page_type == "module_page",
+ Page.target_path.contains(clean_target),
+ )
+ )
+ page = res.scalar_one_or_none()
+ if page:
+ target_type = "module"
+ else:
+ # 3. Try symbol (exact then fuzzy)
+ res = await session.execute(
+ select(WikiSymbol).where(
+ WikiSymbol.repository_id == repo_id,
+ WikiSymbol.name == target,
+ )
+ )
+ sym_matches = list(res.scalars().all())
+ if not sym_matches:
+ res = await session.execute(
+ select(WikiSymbol)
+ .where(
+ WikiSymbol.repository_id == repo_id,
+ WikiSymbol.name.ilike(f"%{target}%"),
+ )
+ .limit(10)
+ )
+ sym_matches = list(res.scalars().all())
+ if sym_matches:
+ target_type = "symbol"
+ file_path_for_git = sym_matches[0].file_path
+ else:
+ # 4. Try file page by target_path search
+ res = await session.execute(
+ select(Page).where(
+ Page.repository_id == repo_id,
+ Page.page_type == "file_page",
+ Page.target_path == target,
+ )
+ )
+ page = res.scalar_one_or_none()
+ if page:
+ target_type = "file"
+ file_path_for_git = target
+
+ if target_type is None:
+ # Fallback 1: index-only mode (no wiki pages) — return graph node + symbols if present
+ res = await session.execute(
+ select(GraphNode).where(
+ GraphNode.repository_id == repo_id,
+ GraphNode.node_id == target,
+ )
+ )
+ gnode = res.scalar_one_or_none()
+ if gnode is not None:
+ target_type = "file"
+ file_path_for_git = target
+ page = None # no wiki page; subsequent blocks must guard for this
+
+ # Fallback 2: check git_metadata — file may exist but have no wiki page AND no graph node
+ if target_type is None:
+ res = await session.execute(
+ select(GitMetadata).where(
+ GitMetadata.repository_id == repo_id,
+ GitMetadata.file_path == target,
+ )
+ )
+ meta = res.scalar_one_or_none()
+ if meta:
+ return {
+ "target": target,
+ "error": (
+ f"'{target}' exists in the repository but has no wiki page. "
+ "This usually means the file has too few symbols or is below "
+ "the PageRank threshold. Run `repowise update` to regenerate docs."
+ ),
+ "exists_in_git": True,
+ "last_commit_at": meta.last_commit_at.isoformat()
+ if meta.last_commit_at
+ else None,
+ "primary_owner": meta.primary_owner_name,
+ "is_hotspot": meta.is_hotspot,
+ }
+
+ # Fallback 3: fuzzy path suggestions — match by filename or partial path.
+ # Only runs if the prior fallbacks didn't resolve the target.
+ if target_type is None:
+ # For directory-like targets, suggest files within that directory
+ dir_prefix = clean_target.rstrip("/") + "/"
+ res = await session.execute(
+ select(GitMetadata.file_path)
+ .where(
+ GitMetadata.repository_id == repo_id,
+ GitMetadata.file_path.like(f"{dir_prefix}%"),
+ )
+ .limit(5)
+ )
+ suggestions = [row[0] for row in res.all()]
+ if not suggestions:
+ # Fall back to filename / partial path match
+ tail = target.rsplit("/", 1)[-1]
+ res = await session.execute(
+ select(GitMetadata.file_path)
+ .where(
+ GitMetadata.repository_id == repo_id,
+ GitMetadata.file_path.contains(tail),
+ )
+ .limit(5)
+ )
+ suggestions = [row[0] for row in res.all() if row[0] != target]
+ if suggestions:
+ return {
+ "target": target,
+ "error": f"Target not found: '{target}'",
+ "suggestions": suggestions,
+ }
+ return {"target": target, "error": f"Target not found: '{target}'"}
+
+ result_data["target"] = target
+ result_data["type"] = target_type
+
+ # --- Docs ---
+ # "full_doc" implies "docs" — entering the docs block whenever either is requested.
+ if include is None or "docs" in include or "full_doc" in include:
+ want_full_doc = bool(include and "full_doc" in include)
+ docs: dict[str, Any] = {}
+ if target_type == "file":
+ if page is not None:
+ docs["title"] = page.title
+ docs["summary"] = page.summary or ""
+ if want_full_doc:
+ docs["content_md"] = page.content
+ if page.human_notes:
+ docs["human_notes"] = page.human_notes
+ # Symbols in this file
+ res = await session.execute(
+ select(WikiSymbol).where(
+ WikiSymbol.repository_id == repo_id,
+ WikiSymbol.file_path == 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")]
+ if compact:
+ # Compact mode: name+kind+signature+line+symbol_id only. Drops
+ # docstrings, line ranges, structure, and imported_by — those
+ # live behind compact=False or include= flags. The symbol_id
+ # is the canonical handle the caller pipes straight into
+ # get_symbol when it wants bytes.
+ #
+ # Cap at 40 symbols so a dense generated file (protobuf
+ # wrappers, vendored libs) can't blow the triage card past
+ # the agent's budget. Order matches WikiSymbol.start_line
+ # (assigned at index time), so the head is the navigationally
+ # useful slice.
+ symbol_cap = 40
+ visible = list(symbols)[:symbol_cap]
+ docs["symbols"] = [
+ {
+ "name": s.name,
+ "kind": s.kind,
+ "signature": s.signature,
+ "line": s.start_line,
+ "symbol_id": s.symbol_id,
+ }
+ for s in visible
+ ]
+ if len(symbols) > symbol_cap:
+ docs["symbols_truncated"] = {
+ "shown": symbol_cap,
+ "total": len(symbols),
+ "hint": "Call with compact=False or include=['full_doc'] for the full list.",
+ }
+ if not docs.get("summary"):
+ docs["summary"] = _synthesize_structural_summary(target, classes, functions)
+ else:
+ docs["symbols"] = [
+ {
+ "name": s.name,
+ "kind": s.kind,
+ "signature": s.signature,
+ "start_line": s.start_line,
+ "end_line": s.end_line,
+ "docstring": (s.docstring or "")[:400],
+ }
+ for s in symbols
+ ]
+ # Structure summary block — quick scan of what's in the file
+ total_loc = max((s.end_line for s in symbols), default=0)
+ avg_complexity = (
+ sum(s.complexity_estimate for s in symbols) / len(symbols) if symbols else 0
+ )
+ docs["structure"] = {
+ "classes": classes,
+ "functions": functions,
+ "symbol_count": len(symbols),
+ "total_loc": total_loc,
+ "avg_complexity": round(avg_complexity, 2),
+ }
+ # Fallback summary: if no Page (index-only mode) or page.summary
+ # is empty, synthesize a deterministic one-liner from structure.
+ if not docs.get("summary"):
+ docs["summary"] = _synthesize_structural_summary(target, classes, functions)
+ # Importers
+ res = await session.execute(
+ select(GraphEdge).where(
+ GraphEdge.repository_id == repo_id,
+ GraphEdge.target_node_id == target,
+ )
+ )
+ importers = res.scalars().all()
+ docs["imported_by"] = [e.source_node_id for e in importers]
+
+ # Community info (compact=False only, ~80 bytes)
+ res = await session.execute(
+ select(GraphNode).where(
+ GraphNode.repository_id == repo_id,
+ GraphNode.node_id == target,
+ )
+ )
+ gn = res.scalar_one_or_none()
+ if gn and gn.community_id is not None:
+ _cmeta: dict[str, Any] = {}
+ try:
+ _cmeta = json.loads(gn.community_meta_json or "{}")
+ except (json.JSONDecodeError, TypeError):
+ pass
+ docs["community"] = {
+ "id": gn.community_id,
+ "label": _cmeta.get("label", ""),
+ }
+
+ elif target_type == "module":
+ docs["title"] = page.title
+ docs["summary"] = page.summary or ""
+ if want_full_doc:
+ docs["content_md"] = page.content
+ # Child file pages
+ res = await session.execute(
+ select(Page).where(
+ Page.repository_id == repo_id,
+ Page.page_type == "file_page",
+ Page.target_path.like(f"{page.target_path}/%"),
+ )
+ )
+ file_pages = res.scalars().all()
+ docs["files"] = [
+ {
+ "path": f.target_path,
+ "description": f.title,
+ "confidence_score": f.confidence,
+ }
+ for f in file_pages
+ ]
+
+ elif target_type == "symbol":
+ sym = sym_matches[0] # type: ignore[possibly-undefined]
+ docs["name"] = sym.name
+ docs["qualified_name"] = sym.qualified_name
+ docs["kind"] = sym.kind
+ docs["signature"] = sym.signature
+ docs["file_path"] = sym.file_path
+ docs["docstring"] = sym.docstring or ""
+ # File page summary (full content gated behind include=["full_doc"])
+ sym_page_id = f"file_page:{sym.file_path}"
+ sym_page = await session.get(Page, sym_page_id)
+ if sym_page is not None:
+ docs["file_summary"] = sym_page.summary or ""
+ if want_full_doc:
+ docs["documentation"] = sym_page.content
+ # Used by
+ res = await session.execute(
+ select(GraphEdge).where(
+ GraphEdge.repository_id == repo_id,
+ GraphEdge.target_node_id == sym.file_path,
+ )
+ )
+ edges = res.scalars().all()
+ docs["used_by"] = [e.source_node_id for e in edges][:20]
+ # Candidates
+ if len(sym_matches) > 1: # type: ignore[possibly-undefined]
+ docs["candidates"] = [
+ {"name": m.name, "kind": m.kind, "file_path": m.file_path}
+ for m in sym_matches[1:5] # type: ignore[possibly-undefined]
+ ]
+
+ result_data["docs"] = docs
+
+ # --- Triage signals (always on) ---------------------------------------
+ # Two single-bit-ish pointers the agent uses to decide its next move:
+ # * ``hotspot``: lights the way to ``get_risk`` for files in the 95th+
+ # churn percentile. Just the boolean — the full risk dossier stays
+ # in ``get_risk`` so the triage card doesn't grow.
+ # * ``decision_records``: titles only, no body. Lights the way to
+ # ``get_why``. We deliberately don't inline the rationale here;
+ # duplicating it across every ``get_context`` response bloats the
+ # cached prompt prefix and defeats the split between the two tools.
+ #
+ # Cheap: two short queries piggybacking on the session we already opened.
+ triage_path = file_path_for_git
+ if target_type == "module" and page:
+ triage_path = page.target_path
+ if triage_path:
+ triage_meta_res = await session.execute(
+ select(GitMetadata.is_hotspot).where(
+ GitMetadata.repository_id == repo_id,
+ GitMetadata.file_path == triage_path,
+ )
+ )
+ triage_meta = triage_meta_res.scalar_one_or_none()
+ result_data["hotspot"] = bool(triage_meta) if triage_meta is not None else False
+
+ # Bounded graph-link query — replaces full Python scan over all rows.
+ governing: list[DecisionRecord] = []
+ seen_ids: set[str] = set()
+ for lookup_node in dict.fromkeys(
+ [triage_path, target] if triage_path != target else [triage_path]
+ ):
+ if not lookup_node:
+ continue
+ for dr in await get_governing_decisions(session, repo_id, lookup_node):
+ if dr.id not in seen_ids:
+ seen_ids.add(dr.id)
+ governing.append(dr)
+ if governing:
+ result_data["decision_records"] = [dr.title for dr in governing[:5]]
+ result_data["decision_records_hint"] = (
+ "Decisions touch this file. Call get_why(targets=[...]) for rationale."
+ )
+ # Compact enriched list — highest-confidence first, capped at 5.
+ governing_sorted = sorted(governing, key=lambda d: -(d.confidence or 0.0))
+ result_data["governing_decisions"] = [
+ {
+ "id": dr.id,
+ "title": dr.title,
+ "status": dr.status,
+ "staleness_score": dr.staleness_score,
+ "verification": dr.verification,
+ "stale": bool(dr.status == "active" and (dr.staleness_score or 0.0) >= 0.5),
+ }
+ for dr in governing_sorted[:5]
+ ]
+
+ # --- Ownership ---
+ if include is None or "ownership" in include:
+ ownership: dict[str, Any] = {}
+ git_path = file_path_for_git
+ if target_type == "module" and page:
+ git_path = page.target_path
+ if git_path:
+ res = await session.execute(
+ select(GitMetadata).where(
+ GitMetadata.repository_id == repo_id,
+ GitMetadata.file_path == git_path,
+ )
+ )
+ meta = res.scalar_one_or_none()
+ if meta:
+ ownership["primary_owner"] = meta.primary_owner_name
+ ownership["owner_pct"] = meta.primary_owner_commit_pct
+ ownership["contributor_count"] = getattr(meta, "contributor_count", 0) or len(
+ json.loads(meta.top_authors_json)
+ )
+ ownership["bus_factor"] = getattr(meta, "bus_factor", 0) or 0
+ # Recent owner (who maintains this file now)
+ recent = getattr(meta, "recent_owner_name", None)
+ if recent and recent != meta.primary_owner_name:
+ ownership["recent_owner"] = recent
+ ownership["recent_owner_pct"] = getattr(meta, "recent_owner_commit_pct", None)
+ else:
+ ownership["primary_owner"] = None
+ ownership["owner_pct"] = None
+ ownership["contributor_count"] = 0
+ ownership["bus_factor"] = 0
+ else:
+ ownership["primary_owner"] = None
+ ownership["owner_pct"] = None
+ ownership["contributor_count"] = 0
+ ownership["bus_factor"] = 0
+ result_data["ownership"] = ownership
+
+ # --- Last change ---
+ if include is None or "last_change" in include:
+ last_change: dict[str, Any] = {}
+ git_path = file_path_for_git
+ if target_type == "module" and page:
+ git_path = page.target_path
+ if git_path:
+ res = await session.execute(
+ select(GitMetadata).where(
+ GitMetadata.repository_id == repo_id,
+ GitMetadata.file_path == git_path,
+ )
+ )
+ meta = res.scalar_one_or_none()
+ if meta:
+ last_change["date"] = (
+ meta.last_commit_at.isoformat() if meta.last_commit_at else None
+ )
+ last_change["author"] = meta.primary_owner_name
+ last_change["days_ago"] = meta.age_days
+ else:
+ last_change["date"] = None
+ last_change["author"] = None
+ last_change["days_ago"] = None
+ else:
+ last_change["date"] = None
+ last_change["author"] = None
+ last_change["days_ago"] = None
+ result_data["last_change"] = last_change
+
+ # --- Decisions ---
+ if include is None or "decisions" in include:
+ res = await session.execute(
+ select(DecisionRecord).where(
+ DecisionRecord.repository_id == repo_id,
+ )
+ )
+ all_decisions = res.scalars().all()
+ governing = []
+ for d in all_decisions:
+ affected_files = json.loads(d.affected_files_json)
+ affected_modules = json.loads(d.affected_modules_json)
+ if (
+ target in affected_files
+ or target in affected_modules
+ or (file_path_for_git and file_path_for_git in affected_files)
+ ):
+ governing.append(
+ {
+ "id": d.id,
+ "title": d.title,
+ "status": d.status,
+ "decision": d.decision,
+ "rationale": d.rationale,
+ "confidence": d.confidence,
+ }
+ )
+ result_data["decisions"] = governing
+
+ # --- Freshness ---
+ if include is None or "freshness" in include:
+ freshness: dict[str, Any] = {}
+ if page:
+ freshness["confidence_score"] = page.confidence
+ freshness["freshness_status"] = page.freshness_status
+ freshness["is_stale"] = (page.confidence or 1.0) < 0.6
+ elif target_type == "symbol" and file_path_for_git:
+ sym_page_id = f"file_page:{file_path_for_git}"
+ sym_page = await session.get(Page, sym_page_id)
+ if sym_page:
+ freshness["confidence_score"] = sym_page.confidence
+ freshness["freshness_status"] = sym_page.freshness_status
+ freshness["is_stale"] = (sym_page.confidence or 1.0) < 0.6
+ else:
+ freshness["confidence_score"] = None
+ freshness["freshness_status"] = None
+ freshness["is_stale"] = None
+ else:
+ freshness["confidence_score"] = None
+ freshness["freshness_status"] = None
+ freshness["is_stale"] = None
+ result_data["freshness"] = freshness
+
+ # --- KG layer + tour context (Phase 9) ---
+ if target_type == "file" and file_path_for_git:
+ kg_layers = await get_kg_layers(session, repo_id)
+ if kg_layers:
+ for _l in kg_layers:
+ _l._parsed_node_ids = json.loads(_l.node_ids_json) if _l.node_ids_json else []
+ file_layer = _find_layer_for_file(file_path_for_git, kg_layers)
+ if file_layer:
+ edge_res = await session.execute(
+ select(GraphEdge).where(
+ GraphEdge.repository_id == repo_id,
+ GraphEdge.target_node_id == file_path_for_git,
+ GraphEdge.edge_type == "imports",
+ )
+ )
+ incoming_edges = list(edge_res.scalars())
+ result_data["architectural_layer"] = {
+ "name": file_layer.name,
+ "description": (file_layer.description or "")[:200],
+ "role": _classify_file_role(file_path_for_git, file_layer, incoming_edges),
+ }
+
+ kg_tour = await get_kg_tour_steps(session, repo_id)
+ if kg_tour:
+ for _s in kg_tour:
+ _s._parsed_node_ids = json.loads(_s.node_ids_json) if _s.node_ids_json else []
+ file_tour_step = _find_tour_step_for_file(file_path_for_git, kg_tour)
+ if file_tour_step:
+ result_data["tour_context"] = {
+ "step": file_tour_step.step_order,
+ "title": file_tour_step.title,
+ "why": (file_tour_step.description or "")[:200],
+ }
+
+ # --- Callers / Callees (replaces get_callers_callees) ---
+ want_callers = bool(include and "callers" in include)
+ want_callees = bool(include and "callees" in include)
+ if want_callers or want_callees:
+ await _resolve_call_graph(
+ session,
+ repository,
+ target,
+ target_type,
+ result_data,
+ want_callers=want_callers,
+ want_callees=want_callees,
+ )
+
+ # --- Metrics (replaces get_graph_metrics) ---
+ if include and "metrics" in include:
+ await _resolve_metrics(session, repository, target, result_data)
+
+ # --- Community (replaces get_community) ---
+ if include and "community" in include:
+ await _resolve_community(session, repository, target, result_data)
+
+ # --- Code health (Phase 2) ---
+ if include and "health" in include:
+ await _resolve_health(session, repository, target, target_type, result_data)
+
+ return result_data
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/truncation.py b/packages/server/src/repowise/server/mcp_server/tool_context/truncation.py
new file mode 100644
index 000000000..33103077e
--- /dev/null
+++ b/packages/server/src/repowise/server/mcp_server/tool_context/truncation.py
@@ -0,0 +1,242 @@
+"""Output-size budgeting for get_context.
+
+The Claude Code harness rejects MCP tool results whose stringified form exceeds
+~10k tokens, so get_context caps its response well below that. This module owns
+the budget constants and the truncation strategy.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# --- Output size budget -------------------------------------------------------
+# The Claude Code harness rejects MCP tool results whose stringified form exceeds
+# ~10k tokens (it refuses to inline them and then refuses to Read the spilled
+# file). When that happens the agent falls back to multiple get_symbol calls,
+# each of which re-plays the cached system prompt — a significant cost driver
+# on dense files in long multi-turn agent sessions.
+#
+# We therefore cap get_context output well below that ceiling. 8000 tokens
+# leaves headroom for the wrapping JSON envelope and _meta fields the harness
+# adds on top. The estimator is intentionally dependency-free: 4 chars/token is
+# the widely-quoted average for English + code on BPE tokenizers and is within
+# ~20% of tiktoken for typical wiki content. Precise counting is unnecessary
+# because we only need to stay comfortably under the hard limit.
+_TOKEN_BUDGET = 8000
+_CHARS_PER_TOKEN = 4
+_CHAR_BUDGET = _TOKEN_BUDGET * _CHARS_PER_TOKEN
+
+
+def _estimate_tokens(obj: Any) -> int:
+ """Cheap upper-bound token estimate for an arbitrary JSON-serialisable object.
+
+ Serialises to compact JSON (the wire format the MCP layer eventually emits)
+ and divides by ``_CHARS_PER_TOKEN``. We use the serialised form — not just
+ raw text fields — because structural JSON overhead (quotes, braces, field
+ names) is non-trivial and is what the downstream tokenizer actually sees.
+ """
+ return len(json.dumps(obj, separators=(",", ":"), default=str)) // _CHARS_PER_TOKEN
+
+
+# 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.
+_HEAVY_DOC_FIELDS: tuple[str, ...] = ("content_md", "documentation", "file_summary")
+
+
+def _symbol_priority(sym: dict[str, Any], query_terms: set[str]) -> tuple[int, int, int]:
+ """Return a sort key (higher = keep) for a symbol within a target.
+
+ Priority order (language-agnostic — no Python-specific heuristics):
+ 1. Exact name match against any user query term.
+ 2. Substring / case-insensitive match against query terms.
+ 3. Kind rank: classes/types outrank functions/methods which outrank the
+ rest. This mirrors navigational usefulness across Python, TS, Go,
+ Rust, C++, etc. where a type anchors a module more than a helper fn.
+ 4. PageRank / centrality if present on the dict (forward-compatible —
+ ``get_context`` doesn't currently populate it but ``_resolve_one_target``
+ may in the future).
+ """
+ name = (sym.get("name") or "").lower()
+ exact = 1 if name and name in query_terms else 0
+ fuzzy = 1 if any(t and t in name for t in query_terms) else 0
+ kind = (sym.get("kind") or "").lower()
+ kind_rank = {
+ "class": 3,
+ "interface": 3,
+ "struct": 3,
+ "trait": 3,
+ "type": 3,
+ "enum": 3,
+ "function": 2,
+ "method": 2,
+ }.get(kind, 1)
+ centrality = int((sym.get("pagerank") or sym.get("centrality") or 0) * 1000)
+ return (exact * 10 + fuzzy * 5 + kind_rank, centrality, -len(json.dumps(sym, default=str)))
+
+
+def _query_terms_for(target: str) -> set[str]:
+ """Derive cheap query terms from a target string for symbol prioritisation.
+
+ ``get_context`` has no explicit query argument, so we fall back to the
+ target identifier itself — the tail of a file path, or the raw symbol name.
+ This is deliberately coarse: it just nudges symbol retention toward the
+ thing the caller asked about.
+ """
+ tail = target.rsplit("/", 1)[-1].lower()
+ # Strip common extension if present (language-agnostic: split once on '.').
+ if "." in tail:
+ tail = tail.rsplit(".", 1)[0]
+ return {t for t in (tail, target.lower()) if t}
+
+
+def _truncate_to_budget(
+ result: dict[str, Any],
+ char_budget: int = _CHAR_BUDGET,
+) -> dict[str, Any]:
+ """Cap the ``get_context`` response at roughly ``_TOKEN_BUDGET`` tokens.
+
+ Strategy (applied in order, stopping as soon as the budget is met):
+
+ 1. **Strip heavy optional doc fields** (``content_md``, ``documentation``,
+ ``file_summary``) from each target. These are 1–2k tokens apiece and
+ duplicate information the agent can re-request via ``full_doc``.
+ 2. **Shrink symbol lists within each target**, keeping the highest-priority
+ symbols per ``_symbol_priority``. This preserves the navigational index
+ (names, signatures, line numbers) while dropping bulk docstrings.
+ 3. **Drop whole targets** from the tail of the list. Per spec we prefer
+ keeping fewer full-fidelity targets over many stubs, so once symbols
+ can't shrink further we evict entire targets rather than gutting them.
+
+ Adds ``truncated: bool``, ``dropped_targets: list[str]``, and
+ ``dropped_symbols: dict[target, list[name]]`` top-level fields — additive
+ only, existing callers are unaffected.
+
+ Edge cases:
+ * Empty ``targets`` → returns unchanged with ``truncated=False``.
+ * A single target whose symbol list alone busts the budget → we reduce
+ symbols down to 1 and accept the overshoot rather than returning an
+ empty response. The ``truncated`` flag still fires.
+ * Targets that carry an ``error`` field (not-found) are cheap and are
+ preserved unless literally nothing else fits.
+ """
+ result.setdefault("truncated", False)
+ result.setdefault("dropped_targets", [])
+ result.setdefault("dropped_symbols", {})
+
+ targets: dict[str, Any] = result.get("targets") or {}
+ if not targets:
+ return result
+
+ def _size() -> int:
+ return len(json.dumps(result, separators=(",", ":"), default=str))
+
+ if _size() <= char_budget:
+ return result
+
+ # Stage 1: strip heavy optional doc fields across all targets.
+ for name, tgt in targets.items():
+ docs = tgt.get("docs") if isinstance(tgt, dict) else None
+ if not isinstance(docs, dict):
+ continue
+ for field in _HEAVY_DOC_FIELDS:
+ if field in docs:
+ docs.pop(field, None)
+ result["truncated"] = True
+ if _size() <= char_budget:
+ return result
+
+ # Stage 2: prioritise symbols within each target. We iterate from the
+ # largest target down so the biggest offenders shrink first.
+ def _target_cost(item: tuple[str, Any]) -> int:
+ return len(json.dumps(item[1], default=str))
+
+ for tgt_name, tgt in sorted(targets.items(), key=_target_cost, reverse=True):
+ docs = tgt.get("docs") if isinstance(tgt, dict) else None
+ if not isinstance(docs, dict):
+ continue
+ symbols = docs.get("symbols")
+ if not isinstance(symbols, list) or not symbols:
+ continue
+ query_terms = _query_terms_for(tgt_name)
+ ordered = sorted(symbols, key=lambda s: _symbol_priority(s, query_terms), reverse=True)
+
+ # Per-symbol greedy fit. The cost of the whole response with a symbol
+ # list ``S`` is exactly:
+ # base + sum(cost(s) for s in S) + max(0, len(S) - 1)
+ # where ``base`` is the response size with this target's ``symbols``
+ # emptied and ``cost(s)`` is the symbol's compact-JSON length. Both are
+ # context-independent under the compact separators we serialise with,
+ # so we precompute each symbol's cost ONCE and track a running sum
+ # instead of re-serialising the entire response per candidate symbol
+ # (the old O(targets × symbols²) behaviour). The keep/drop decision is
+ # byte-for-byte identical to the previous ``_size()``-per-symbol loop.
+ costs = [len(json.dumps(s, separators=(",", ":"), default=str)) for s in ordered]
+ docs["symbols"] = []
+ base = _size()
+ kept: list[dict[str, Any]] = []
+ dropped: list[str] = []
+ sum_kept = 0
+ for sym, cost in zip(ordered, costs, strict=True):
+ # Tentative size if we add this symbol to the current kept set:
+ # the +len(kept) term is the comma separators for kept+1 entries.
+ tentative = base + sum_kept + cost + len(kept)
+ if tentative <= char_budget:
+ kept.append(sym)
+ sum_kept += cost
+ else:
+ dropped.append(sym.get("name") or "<anonymous>")
+ if 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):
+ head["docstring"] = head["docstring"][:200]
+ kept = [head]
+ dropped = [s.get("name") or "<anonymous>" for s in ordered[1:]]
+ docs["symbols"] = kept
+ if dropped:
+ result["dropped_symbols"][tgt_name] = dropped
+ result["truncated"] = True
+ if _size() <= char_budget:
+ return result
+
+ # Stage 3: drop whole targets, largest first, until we fit. Prefer to keep
+ # error-only targets (they're tiny and signal "not found" to the caller).
+ def _evictable_order() -> list[str]:
+ items = list(targets.items())
+ items.sort(
+ key=lambda kv: (
+ 0 if isinstance(kv[1], dict) and "error" in kv[1] else 1,
+ len(json.dumps(kv[1], default=str)),
+ ),
+ reverse=True,
+ )
+ return [k for k, _ in items]
+
+ for name in _evictable_order():
+ if len(targets) <= 1:
+ break
+ targets.pop(name, None)
+ result["dropped_targets"].append(name)
+ result["truncated"] = True
+ if _size() <= char_budget:
+ break
+
+ if result["truncated"]:
+ logger.info(
+ "get_context truncated to budget",
+ extra={
+ "char_budget": char_budget,
+ "token_budget": _TOKEN_BUDGET,
+ "final_chars": _size(),
+ "dropped_targets": result["dropped_targets"],
+ "dropped_symbol_counts": {k: len(v) for k, v in result["dropped_symbols"].items()},
+ },
+ )
+ return result
diff --git a/tests/unit/server/test_truncate_budget_equivalence.py b/tests/unit/server/test_truncate_budget_equivalence.py
new file mode 100644
index 000000000..8222eec67
--- /dev/null
+++ b/tests/unit/server/test_truncate_budget_equivalence.py
@@ -0,0 +1,167 @@
+"""Characterisation test for the _truncate_to_budget O(n^2) -> O(n) optimisation.
+
+The split of ``tool_context.py`` replaced the per-symbol full-response
+re-serialisation in stage 2 of ``_truncate_to_budget`` with a precomputed
+per-symbol cost + running sum. This test pins that the optimised implementation
+produces a **byte-identical** result to the original implementation (embedded
+here verbatim as ``_reference_truncate``) across a range of over-budget fixtures.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+
+import pytest
+
+from repowise.server.mcp_server.tool_context.truncation import (
+ _HEAVY_DOC_FIELDS,
+ _query_terms_for,
+ _symbol_priority,
+ _truncate_to_budget,
+)
+
+
+def _reference_truncate(result: dict, char_budget: int) -> dict:
+ """Verbatim copy of the original (pre-optimisation) _truncate_to_budget.
+
+ Stage 2 re-serialises the whole response once per candidate symbol — the
+ O(targets x symbols^2) behaviour the optimisation removes. Kept here purely
+ as the oracle the optimised implementation must match exactly.
+ """
+ result.setdefault("truncated", False)
+ result.setdefault("dropped_targets", [])
+ result.setdefault("dropped_symbols", {})
+
+ targets = result.get("targets") or {}
+ if not targets:
+ return result
+
+ def _size() -> int:
+ return len(json.dumps(result, separators=(",", ":"), default=str))
+
+ if _size() <= char_budget:
+ return result
+
+ for _name, tgt in targets.items():
+ docs = tgt.get("docs") if isinstance(tgt, dict) else None
+ if not isinstance(docs, dict):
+ continue
+ for field in _HEAVY_DOC_FIELDS:
+ if field in docs:
+ docs.pop(field, None)
+ result["truncated"] = True
+ if _size() <= char_budget:
+ return result
+
+ def _target_cost(item):
+ return len(json.dumps(item[1], default=str))
+
+ for tgt_name, tgt in sorted(targets.items(), key=_target_cost, reverse=True):
+ docs = tgt.get("docs") if isinstance(tgt, dict) else None
+ if not isinstance(docs, dict):
+ continue
+ symbols = docs.get("symbols")
+ if not isinstance(symbols, list) or not symbols:
+ continue
+ query_terms = _query_terms_for(tgt_name)
+ ordered = sorted(symbols, key=lambda s: _symbol_priority(s, query_terms), reverse=True)
+ kept: list[dict] = []
+ dropped: list[str] = []
+ for sym in ordered:
+ docs["symbols"] = [*kept, sym]
+ if _size() <= char_budget:
+ kept.append(sym)
+ else:
+ dropped.append(sym.get("name") or "<anonymous>")
+ if not kept and ordered:
+ head = dict(ordered[0])
+ if isinstance(head.get("docstring"), str):
+ head["docstring"] = head["docstring"][:200]
+ kept = [head]
+ dropped = [s.get("name") or "<anonymous>" for s in ordered[1:]]
+ docs["symbols"] = kept
+ if dropped:
+ result["dropped_symbols"][tgt_name] = dropped
+ result["truncated"] = True
+ if _size() <= char_budget:
+ return result
+
+ def _evictable_order():
+ items = list(targets.items())
+ items.sort(
+ key=lambda kv: (
+ 0 if isinstance(kv[1], dict) and "error" in kv[1] else 1,
+ len(json.dumps(kv[1], default=str)),
+ ),
+ reverse=True,
+ )
+ return [k for k, _ in items]
+
+ for name in _evictable_order():
+ if len(targets) <= 1:
+ break
+ targets.pop(name, None)
+ result["dropped_targets"].append(name)
+ result["truncated"] = True
+ if _size() <= char_budget:
+ break
+
+ return result
+
+
+def _make_response(n_targets: int, n_symbols: int, body_chars: int, docstring_chars: int) -> dict:
+ """Build a synthetic get_context response large enough to exceed a budget."""
+ targets: dict[str, dict] = {}
+ for ti in range(n_targets):
+ path = f"src/pkg{ti}/module_{ti}.py"
+ symbols = [
+ {
+ "name": f"sym_{ti}_{si}",
+ "kind": ["class", "function", "method", "helper"][si % 4],
+ "signature": f"def sym_{ti}_{si}(arg0, arg1, arg2) -> None",
+ "start_line": si * 5 + 1,
+ "end_line": si * 5 + 4,
+ "docstring": ("d" * docstring_chars),
+ }
+ for si in range(n_symbols)
+ ]
+ targets[path] = {
+ "target": path,
+ "type": "file",
+ "docs": {
+ "title": f"Module {ti}",
+ "summary": "s" * 80,
+ "content_md": "m" * body_chars,
+ "symbols": symbols,
+ },
+ "hotspot": ti % 2 == 0,
+ }
+ return {"targets": targets, "_meta": {"timing_ms": 1.0}}
+
+
+ ("n_targets", "n_symbols", "body_chars", "docstring_chars", "budget"),
+ [
+ (4, 30, 4000, 120, 8000),
+ (6, 60, 5000, 200, 8000),
+ (1, 200, 0, 300, 8000), # single dense target, busts on symbols alone
+ (3, 10, 0, 50, 2000), # tiny budget forces target eviction
+ (10, 5, 1500, 40, 6000),
+ (2, 1, 0, 50000, 4000), # single symbol larger than budget
+ ],
+)
+def test_optimised_matches_reference(n_targets, n_symbols, body_chars, docstring_chars, budget):
+ fixture = _make_response(n_targets, n_symbols, body_chars, docstring_chars)
+
+ optimised = _truncate_to_budget(copy.deepcopy(fixture), char_budget=budget)
+ reference = _reference_truncate(copy.deepcopy(fixture), char_budget=budget)
+
+ # Byte-identical serialisation is the strongest possible equality check.
+ assert json.dumps(optimised, sort_keys=True, default=str) == json.dumps(
+ reference, sort_keys=True, default=str
+ )
+ # And the structural bookkeeping fields match exactly.
+ assert optimised["truncated"] == reference["truncated"]
+ assert optimised["dropped_targets"] == reference["dropped_targets"]
+ assert optimised["dropped_symbols"] == reference["dropped_symbols"]