From bb6204ff172eead705e035e8630f361e2b9dc2fe Mon Sep 17 00:00:00 2001 From: Lareb Zafar Date: Sat, 21 Nov 2026 17:51:50 +0530 Subject: [PATCH 1/8] Code search defaults to an unlimited response budget Make token limits an explicit deployment or request choice, including MCP and cursor pages. Keep finite budgets on recomputed cursor pages and document server configuration. Signed-off-by: Lareb Zafar --- docs/features/code-index/operations.md | 10 +++ docs/reference/configuration.md | 1 + docs/reference/operations/code.md | 2 +- loom.example.yaml | 4 + schemas/loom-settings.schema.json | 6 ++ server/code/api/models_search.py | 7 +- server/code/app/search/handler.py | 22 +++-- server/code/app/search/history.py | 4 +- server/code/app/search/pipeline.py | 2 +- server/code/app/search/serve.py | 4 +- server/code/app/search/shared.py | 11 +-- server/code/domain/units.py | 11 ++- server/settings/catalog.py | 3 + server/transport/mcp_defaults.py | 11 +-- .../test_code_search_token_budget.py | 84 +++++++++++++++++++ tests/unit/snapshots/settings_defaults.json | 1 + tests/unit/test_code_budget_tiers.py | 3 +- tests/unit/test_code_search_cursor.py | 38 ++++++--- tests/unit/test_code_search_token_budget.py | 75 +++++++++++++++++ tests/unit/test_mcp_defaults.py | 8 +- 20 files changed, 255 insertions(+), 52 deletions(-) create mode 100644 tests/integration/test_code_search_token_budget.py create mode 100644 tests/unit/test_code_search_token_budget.py diff --git a/docs/features/code-index/operations.md b/docs/features/code-index/operations.md index a3067dc946..3d81a124d9 100644 --- a/docs/features/code-index/operations.md +++ b/docs/features/code-index/operations.md @@ -129,6 +129,16 @@ located = await agent.code.enclosing(["src/quota/limiter.py:88", "src/api/routes `bodies: "none"` (spans and signatures only, the cheapest answer), `token_budget`, `expand` (one LLM hop to bridge wording to identifiers) and `cursor` for the next page. +`code.search` has no response token cap by default. Set +`LOOM_CODE_SEARCH_TOKEN_BUDGET` to a positive token count to set a deployment default; +`0` means unlimited. A request's `token_budget` overrides that default, including +`token_budget: 0` for an unlimited response. This applies to HTTP and MCP, cursor pages +and searches across repositories. `top_k` still limits the number of results per page, +and `bodies: "none"` still returns pointers without code bodies (the MCP default). + +For a Compose installation, put the variable in the `.env` file beside `compose.yaml` +and recreate the server container after changing it. + ## Follow a specification to code and back Repository Markdown and imported knowledge documents take different paths. An indexed diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index a80be64230..3dbe62bec9 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -647,6 +647,7 @@ The code index's network git (clone, fetch, ls-remote, submodule update) through | `LOOM_CODE_RISK_ANNOTATIONS` | `bool` | `True` | | Per-result risk annotations (churn/amp/tested) and one-hop callee context on code.search results; reserves part of the token budget. Kill switch. | | `LOOM_CODE_UNIT_RISK_MAX_AGE_S` | `int` | `864000` | | Age (seconds) past which a risk row is stale and annotated live; must exceed the weekly pass interval. | | `LOOM_CODE_SEARCH_BODIES_DEFAULT` | `'auto' \| 'none'` | `'auto'` | | code.search `bodies` when the request omits it: "auto" fills bodies into the budget; "none" serves handles only. | +| `LOOM_CODE_SEARCH_TOKEN_BUDGET` | `int` | `0` | | code.search response budget in tokens when the request omits token_budget; 0 = unlimited. An explicit request budget overrides this default. | | `LOOM_CODE_SEARCH_MEMO_ENABLED` | `bool` | `True` | | Memoise served code.search responses per (org, namespace, request shape) in loom.code_search_memo and replay within the TTL (route "+memo"); `fresh=true` bypasses it. | | `LOOM_CODE_SEARCH_MEMO_TTL_S` | `int` | `1800` | | Seconds a memoised response, and a cursor's stored pool, stay replayable. | | `LOOM_CODE_SEARCH_MEMO_MAX_PAYLOAD_BYTES` | `int` | `200000` | | Max bytes of a response the memo stores; a larger one is not memoised. 0 = no cap. | diff --git a/docs/reference/operations/code.md b/docs/reference/operations/code.md index 97032eba01..68a12e78d0 100644 --- a/docs/reference/operations/code.md +++ b/docs/reference/operations/code.md @@ -1445,7 +1445,7 @@ Search the shared code index of this repository (fresh to the last merged PR). | `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) | | `query` | `str` | required | The question, identifier or phrase to search for; a symbol-shaped query tries the symbol table first (`route` says which path answered). | | `top_k` | `int` | `5` | At most this many results per page (1-25). | -| `token_budget` | `int \| None` | `None` | Response budget in tokens; results are whole units, overflow elides. | +| `token_budget` | `int \| None` | `None` | Response budget in tokens; 0 = unlimited, omitted = LOOM_CODE_SEARCH_TOKEN_BUDGET (default 0). | | `path_prefix` | `str` | `''` | Keep only units whose path starts with this prefix; "" = the whole namespace. | | `cursor` | `str` | `''` | Continuation: the `next_cursor` of an earlier response to this query. | | `exclude_unit_ids` | `list[str]` | *(computed)* | The caller's seen-set: unit ids not to serve again. | diff --git a/loom.example.yaml b/loom.example.yaml index 523368cf27..c1146611b2 100644 --- a/loom.example.yaml +++ b/loom.example.yaml @@ -1971,6 +1971,10 @@ settings: # "none" serves handles only. [restart] # code_search_bodies_default: "auto" + # code.search response budget in tokens when the request omits token_budget; 0 = + # unlimited. An explicit request budget overrides this default. [restart] + # code_search_token_budget: 0 + # Memoise served code.search responses per (org, namespace, request shape) in # loom.code_search_memo and replay within the TTL (route "+memo"); `fresh=true` # bypasses it. [restart] diff --git a/schemas/loom-settings.schema.json b/schemas/loom-settings.schema.json index dea7d18cc5..9ca4e72b52 100644 --- a/schemas/loom-settings.schema.json +++ b/schemas/loom-settings.schema.json @@ -2164,6 +2164,12 @@ "type": "number", "description": "Lexical list's RRF weight for a responsibility question (vector = 1.0). 1.0 = equal weights." }, + "code_search_token_budget": { + "default": 0, + "minimum": 0, + "type": "integer", + "description": "code.search response budget in tokens when the request omits token_budget; 0 = unlimited. An explicit request budget overrides this default." + }, "code_search_vector_model_default": { "default": "", "type": "string", diff --git a/server/code/api/models_search.py b/server/code/api/models_search.py index 67d01dc2b8..6dd03a3429 100644 --- a/server/code/api/models_search.py +++ b/server/code/api/models_search.py @@ -51,10 +51,9 @@ def _clip_query(cls, v: Any) -> Any: # At most this many results per page (1-25). top_k: int = Field(default=5, ge=1, le=25) - # Response budget in tokens; results are whole units, overflow elides. - # None = route-aware default: 3000 for hybrid retrieval, 1200 for a - # symbol-shaped query. Explicit values are honored unchanged. - token_budget: int | None = Field(default=None, ge=200, le=12000) + # Response budget in tokens; 0 = unlimited, omitted = LOOM_CODE_SEARCH_TOKEN_BUDGET + # (default 0). Whole unit bodies that exceed a finite budget are elided. + token_budget: int | None = Field(default=None, ge=0) # Keep only units whose path starts with this prefix; "" = the whole namespace. A prefix # outside the indexed prefixes abstains with `abstain_code=not_covered`. path_prefix: str = "" diff --git a/server/code/app/search/handler.py b/server/code/app/search/handler.py index 19c18db1aa..9182c394a4 100644 --- a/server/code/app/search/handler.py +++ b/server/code/app/search/handler.py @@ -35,6 +35,7 @@ with_stage_ms, ) from server.code.domain import deadline as code_deadline +from server.code.domain.units import remaining_token_budget from server.code.store.index import CodeRepo from server.core.ch import caller_shaped from server.core.llm_free import reads_llm_free @@ -177,7 +178,7 @@ async def _code_search(input: CodeSearchInput) -> CodeSearchOutput: query=input.query, extra_terms=extra_terms, top_k=input.top_k, - token_budget=max(200, token_budget - reserve), + token_budget=remaining_token_budget(token_budget, reserve), path_prefix=input.path_prefix, exclude_unit_ids=input.exclude_unit_ids or None, user_recent_dirs=recent_dirs or None, @@ -585,7 +586,7 @@ async def _serve_search_page( # the plan page 1 resolved plan = page_plan(input) units, tokens = budget_units( - units, max(200, plan.token_budget - plan.reserve), bodies=plan.bodies + units, remaining_token_budget(plan.token_budget, plan.reserve), bodies=plan.bodies ) if plan.annotate and units: try: @@ -686,23 +687,25 @@ async def _page_by_research( offset, and disclose why. The recomputed call issues its own cursor for the page after this one.""" from server.code.app import search_cursor as paging - from server.code.app.search import _POOL_KEEP, classify_query_shape - from server.code.domain.units import estimate_unit_tokens + from server.code.app.search import _POOL_KEEP + from server.code.domain.units import budget_units size = input.top_k want = max(size, min(_POOL_KEEP, offset + size)) - budget = input.token_budget or (1200 if classify_query_shape(input.query) == "symbol" else 3000) + plan = page_plan(input) + budget = plan.token_budget fresh = input.model_copy( update={ "cursor": "", "top_k": want, "fresh": True, - "token_budget": min(12000, int(budget * want / size)), + "token_budget": budget * want // size, } ) out = await handle_code_search(fresh) - out.results = out.results[offset : offset + size] - out.tokens_returned = sum(estimate_unit_tokens(u) for u in out.results) + out.results, out.tokens_returned = budget_units( + out.results[offset : offset + size], budget, bodies=plan.bodies + ) out.route = f"{out.route}+page_fallback" out.as_of = paging.disclose(out.as_of, page_commit="", offset=offset, fallback=reason) set_code_span_attributes(page_offset=offset, page_fallback=reason) @@ -734,6 +737,9 @@ async def _escalate_top_to_file( ) -> None: """The whole-file escalation of the top hit when at least 2000 tokens of the budget survive body-fill and the request's time budget has room; never fails the search.""" + # Unlimited unit bodies do not request a broader whole-file result. + if not token_budget: + return leftover = token_budget - res.tokens_returned if leftover < 2000 or not _budget_allows(res.budget, "whole-file expansion", _LATE_READ_MS): return diff --git a/server/code/app/search/history.py b/server/code/app/search/history.py index f4e2886024..5f40050a3c 100644 --- a/server/code/app/search/history.py +++ b/server/code/app/search/history.py @@ -11,7 +11,7 @@ from server.code.app import history as code_history from server.code.app.search.state import _model_name, _SearchState from server.code.app.spans import code_span, span_attrs -from server.code.domain.units import CodeUnit, budget_units +from server.code.domain.units import CodeUnit, budget_units, remaining_token_budget from server.code.store.index import CodeRepo from server.core import bm25 from server.settings import settings @@ -188,7 +188,7 @@ def _serve_history_anchors( result.history = history_section with code_span("search.bodies", route=result.route): result.units, result.tokens_returned = budget_units( - ranked_h[:top_k], max(200, token_budget - section_tokens), bodies=bodies + ranked_h[:top_k], remaining_token_budget(token_budget, section_tokens), bodies=bodies ) result.tokens_returned += section_tokens result.retrieval_risk = "medium" diff --git a/server/code/app/search/pipeline.py b/server/code/app/search/pipeline.py index d484c12d70..af909ba40d 100644 --- a/server/code/app/search/pipeline.py +++ b/server/code/app/search/pipeline.py @@ -28,7 +28,7 @@ async def search( *, query: str, top_k: int = 5, - token_budget: int = 3000, + token_budget: int = 0, path_prefix: str = "", # the caller's seen-set: dropped from the fused list after fusion and # before diversification (pushing NOT IN into the legs saves nothing) diff --git a/server/code/app/search/serve.py b/server/code/app/search/serve.py index c7661cd3b3..0d302c6fec 100644 --- a/server/code/app/search/serve.py +++ b/server/code/app/search/serve.py @@ -10,7 +10,7 @@ from server.code.app.search.state import _model_name, _SearchState from server.code.app.search.track import _track from server.code.app.spans import code_span -from server.code.domain.units import CodeUnit, budget_units +from server.code.domain.units import CodeUnit, budget_units, remaining_token_budget from server.code.store.index import CodeRepo from server.memory.domain.retrieval_calibration import RetrievalCalibration, finalize_abstain @@ -105,7 +105,7 @@ async def _serve_page( result.history = history_section with code_span("search.bodies", route=result.route): result.units, result.tokens_returned = budget_units( - ranked[:top_k], max(200, token_budget - section_tokens), bodies=bodies + ranked[:top_k], remaining_token_budget(token_budget, section_tokens), bodies=bodies ) result.tokens_returned += section_tokens if constrained and scope is not None: diff --git a/server/code/app/search/shared.py b/server/code/app/search/shared.py index 9b629cd14d..08fa979296 100644 --- a/server/code/app/search/shared.py +++ b/server/code/app/search/shared.py @@ -42,16 +42,13 @@ class PagePlan: def page_plan(inp: Any) -> PagePlan: """The page plan of a CodeSearchInput. Page 1, every cursor page and the fan-out - resolve it here, so a continuation page is budgeted exactly as page 1 was. The - budget default is route-aware: 1200 for a symbol-shaped query (an exact symbol - lookup rarely needs the hybrid default's headroom, even when it falls through to - hybrid), 3000 otherwise; an explicit budget is honored unchanged.""" + resolve it here. An omitted budget takes the deployment default; zero means + unlimited for every query shape and an explicit budget is honored unchanged.""" from server.code.app import risk as code_risk - from server.code.app.search.shape import classify_query_shape from server.settings import settings as _settings - token_budget = inp.token_budget or ( - 1200 if classify_query_shape(inp.query) == "symbol" else 3000 + token_budget = ( + inp.token_budget if inp.token_budget is not None else _settings.code_search_token_budget ) annotate = bool(inp.annotate and _settings.code_risk_annotations) return PagePlan( diff --git a/server/code/domain/units.py b/server/code/domain/units.py index 027015af25..f3820d0078 100644 --- a/server/code/domain/units.py +++ b/server/code/domain/units.py @@ -227,10 +227,15 @@ def unit_from_symbol(row: dict[str, Any], *, body: str = "") -> CodeUnit: ) +def remaining_token_budget(token_budget: int, spent: int) -> int: + """Subtract overhead from a finite budget; keep zero as unlimited.""" + return max(1, token_budget - spent) if token_budget else 0 + + def budget_units( units: list[CodeUnit], token_budget: int, *, bodies: str = "auto" ) -> tuple[list[CodeUnit], int]: - """Two-pass budget fill. Returns (units, tokens_used). + """Two-pass budget fill; zero means unlimited. Returns (units, tokens_used). Pass 1 reserves HEAD room (signature + doc + pointer) for as many ranked units as fit, so every requested slot is represented at least elided. Pass 2 spends the @@ -251,7 +256,7 @@ def budget_units( kept = 0 reserved = 0 for h in heads: - if reserved + h > token_budget: + if token_budget and reserved + h > token_budget: break reserved += h kept += 1 @@ -262,7 +267,7 @@ def budget_units( body_cost = estimate_unit_tokens(u) - _h if u.body else 0 if not u.body: out.append(u) # bodyless (symbol units): whole, not "elided" - elif bodies != "none" and used + body_cost <= token_budget: + elif bodies != "none" and (not token_budget or used + body_cost <= token_budget): out.append(u) used += body_cost else: diff --git a/server/settings/catalog.py b/server/settings/catalog.py index aa657c59b5..49cd53beef 100644 --- a/server/settings/catalog.py +++ b/server/settings/catalog.py @@ -1657,6 +1657,9 @@ def _check_git_proxy(self) -> CodeSettings: # code.search `bodies` when the request omits it: "auto" fills bodies into # the budget; "none" serves handles only. code_search_bodies_default: Literal["auto", "none"] = "auto" + # code.search response budget in tokens when the request omits token_budget; + # 0 = unlimited. An explicit request budget overrides this default. + code_search_token_budget: int = Field(default=0, ge=0) # Memoise served code.search responses per (org, namespace, request shape) # in loom.code_search_memo and replay within the TTL (route "+memo"); # `fresh=true` bypasses it. diff --git a/server/transport/mcp_defaults.py b/server/transport/mcp_defaults.py index 96b5dc23d3..40912519a9 100644 --- a/server/transport/mcp_defaults.py +++ b/server/transport/mcp_defaults.py @@ -9,12 +9,9 @@ watermarks, lags and tiers. So over MCP the op defaults to `brief: true`, and a model that wants the rest passes `brief: false`. -`code.search` over MCP answers within 1,500 tokens: every ranked unit's path, lines, -symbol and description, and a body only where it fits. Every token a tool returns is -re-read on each later turn of the session, and an agent opens the one unit it needs -with a ranged read; the HTTP default (3,000) fills bodies first. Over MCP it -returns pointers and descriptions, no bodies: an agent reads the range it picks, -and a body it did not pick is paid for on every later turn. +`code.search` over MCP returns pointers and descriptions by default, with bodies +available on request. Its token budget follows the same deployment default as HTTP: +unlimited unless configured or supplied by the caller. `code.symbol` over MCP leaves out the recent PRs (about a third of a definition's tokens): they serve a review, not a where/how lookup, and a model that wants them @@ -36,7 +33,7 @@ MCP_DEFAULT_ARGUMENTS: dict[str, dict[str, Any]] = { "code.index_status": {"brief": True}, - "code.search": {"token_budget": 1500, "bodies": "none"}, + "code.search": {"bodies": "none"}, "code.symbol": {"include_history": False}, "code.grep": {"limit": 10}, } diff --git a/tests/integration/test_code_search_token_budget.py b/tests/integration/test_code_search_token_budget.py new file mode 100644 index 0000000000..a49196f5e6 --- /dev/null +++ b/tests/integration/test_code_search_token_budget.py @@ -0,0 +1,84 @@ +"""Search real indexed bodies with unlimited, deployment and request budgets.""" + +from __future__ import annotations + +from collections.abc import AsyncIterator +from typing import Any + +import pytest + +from tests.integration._resources import unique_org + +pytestmark = pytest.mark.asyncio + + +@pytest.fixture +async def code_repo(ch_client: Any) -> AsyncIterator[Any]: + from server.code.store.index import CodeRepo + from server.core.ch import get_client + + client = get_client() + await client.connect() + try: + yield CodeRepo() + finally: + await client.disconnect() + + +@pytest.mark.parametrize("annotate", [False, True]) +async def test_search_keeps_full_bodies_unless_a_budget_is_supplied( + code_repo: Any, monkeypatch: pytest.MonkeyPatch, annotate: bool +) -> None: + from server.code.api.models_search import CodeSearchInput + from server.code.app.index.ingest import ingest_file + from server.code.app.search.handler import handle_code_search + from server.embedding.fake import FakeNGramEmbedder + from server.settings import settings + + org, ns = unique_org("code-budget"), "code-budget" + embedder = FakeNGramEmbedder(dim=settings.embedding_dim) + for i in range(5): + source = ( + f"void retry_transport_{i}() {{\n" + + "// retry operation after transient transport failure in connection pool\n" * 70 + + "}\n" + ).encode() + await ingest_file( + code_repo, + org, + ns, + path=f"src/retry{i}.cpp", + source=source, + commit_sha="a" * 40, + embedding_model=embedder.model_name, + embedder=embedder, + ) + + monkeypatch.setattr(settings, "code_search_token_budget", 0) + request = CodeSearchInput( + org=org, + namespace=ns, + query="retry transient transport connection", + top_k=5, + bodies="auto", + legs="lexical", + fresh=True, + annotate=annotate, + include_lessons=False, + deadline_ms=0, + rerank="none", + embedding_model=embedder.model_name, + ) + unlimited = await handle_code_search(request) + assert not unlimited.abstain and len(unlimited.results) == 5 + assert unlimited.tokens_returned > 3000 + assert all(u.body and not u.elided for u in unlimited.results) + + monkeypatch.setattr(settings, "code_search_token_budget", 1000) + bounded = await handle_code_search(request) + assert bounded.tokens_returned <= 1000 + assert any(u.elided for u in bounded.results) + for budget in (0, 20000): + overridden = await handle_code_search(request.model_copy(update={"token_budget": budget})) + assert [u.body for u in overridden.results] == [u.body for u in unlimited.results] + assert overridden.tokens_returned == unlimited.tokens_returned diff --git a/tests/unit/snapshots/settings_defaults.json b/tests/unit/snapshots/settings_defaults.json index a44ad873f5..d09906208a 100644 --- a/tests/unit/snapshots/settings_defaults.json +++ b/tests/unit/snapshots/settings_defaults.json @@ -386,6 +386,7 @@ "code_search_rerank_kinds": "responsibility", "code_search_rerank_top": 20, "code_search_rrf_lexical_weight_responsibility": 1.0, + "code_search_token_budget": 0, "code_search_vector_model_default": "", "code_search_vector_models": "", "code_search_vector_shortlist": 0, diff --git a/tests/unit/test_code_budget_tiers.py b/tests/unit/test_code_budget_tiers.py index e7fbdd0901..f8f748ef59 100644 --- a/tests/unit/test_code_budget_tiers.py +++ b/tests/unit/test_code_budget_tiers.py @@ -1,5 +1,4 @@ -"""Budget-adaptive granularity: cards floor, escalation pointers, and the -route-aware default. Whole-file expansion is unit-tested at the helper.""" +"""Budget-adaptive granularity: cards, escalation pointers and whole-file expansion.""" from __future__ import annotations diff --git a/tests/unit/test_code_search_cursor.py b/tests/unit/test_code_search_cursor.py index bd5cb68ae2..7c716532f3 100644 --- a/tests/unit/test_code_search_cursor.py +++ b/tests/unit/test_code_search_cursor.py @@ -293,21 +293,28 @@ def test_last_page_has_no_cursor(monkeypatch: pytest.MonkeyPatch) -> None: assert not out.has_more and out.next_cursor == "" and "page_stale" not in out.as_of -def test_page_plan_is_route_aware_and_honours_an_explicit_budget() -> None: - assert shared.page_plan(_inp(query="MergeTreeData::loadDataParts")).token_budget == 1200 - assert shared.page_plan(_inp()).token_budget == 3000 +@pytest.mark.parametrize("default", [0, 2400]) +def test_page_plan_uses_the_deployment_budget_and_honours_the_request( + monkeypatch: pytest.MonkeyPatch, default: int +) -> None: + monkeypatch.setattr(settings, "code_search_token_budget", default) + assert shared.page_plan(_inp(query="MergeTreeData::loadDataParts")).token_budget == default + assert shared.page_plan(_inp()).token_budget == default assert shared.page_plan(_inp(query="MergeTreeData::loadDataParts", token_budget=500)) == ( shared.PagePlan(token_budget=500, bodies="auto", annotate=False, reserve=0) ) + assert shared.page_plan(_inp(token_budget=0)).token_budget == 0 + assert shared.page_plan(_inp(token_budget=20000)).token_budget == 20000 +@pytest.mark.parametrize("default", [0, 1400]) def test_page_two_of_a_symbol_query_is_budgeted_as_page_one( - monkeypatch: pytest.MonkeyPatch, + monkeypatch: pytest.MonkeyPatch, default: int ) -> None: - """A symbol-shaped query that fell through to hybrid was budgeted at 1200 on page 1; - its continuation page fills bodies under the same budget.""" + """A continuation uses the same deployment budget as the first page.""" from server.code.domain import units as units_mod + monkeypatch.setattr(settings, "code_search_token_budget", default) inp = _inp(query="MergeTreeData::loadDataParts", top_k=2) cursor = paging.encode(kind="s", run_id="run1", offset=2, params=_ph(inp), indexed_commit="") row = {"payload": _payload(6), "indexed_commit": "", "created_at": None} @@ -321,7 +328,7 @@ def spy(units: Any, token_budget: int, **kw: Any) -> Any: monkeypatch.setattr(units_mod, "budget_units", spy) asyncio.run(h.handle_code_search(inp.model_copy(update={"cursor": cursor}))) - assert budgets == [shared.page_plan(inp).token_budget] == [1200] + assert budgets == [shared.page_plan(inp).token_budget] == [default] def test_cursor_for_another_query_is_a_400(monkeypatch: pytest.MonkeyPatch) -> None: @@ -339,10 +346,12 @@ def test_cursor_for_another_query_is_a_400(monkeypatch: pytest.MonkeyPatch) -> N asyncio.run(h.handle_code_search(inp)) +@pytest.mark.parametrize("budget", [None, 0, 3000, 20000]) def test_missing_pool_row_falls_back_to_a_disclosed_research( - monkeypatch: pytest.MonkeyPatch, + monkeypatch: pytest.MonkeyPatch, budget: int | None ) -> None: - inp = _inp(top_k=2) + monkeypatch.setattr(settings, "code_search_token_budget", 0) + inp = _inp(top_k=2, token_budget=budget) ph = paging.params_hash(inp, rerank="", embedding_model="m") cursor = paging.encode(kind="s", run_id="gone", offset=2, params=ph, indexed_commit="") _drive(monkeypatch, inp, None) @@ -352,7 +361,10 @@ async def _fresh(fresh_inp: CodeSearchInput): from server.code.api.models_search import CodeSearchOutput seen.append(fresh_inp) - units = [CodeUnit(unit_id=f"c{i}", path="p", score=1.0, body="b") for i in range(4)] + units = [ + CodeUnit(unit_id=f"c{i}", path="p", score=1.0, body="b" * (10000 if i >= 2 else 1)) + for i in range(4) + ] return CodeSearchOutput( results=units, route="hybrid", @@ -368,8 +380,12 @@ async def _fresh(fresh_inp: CodeSearchInput): ) ) assert seen[0].cursor == "" and seen[0].top_k == 4 and seen[0].fresh is True - assert seen[0].token_budget == 6000 # scaled with the depth + assert seen[0].token_budget == (budget or 0) * 2 # scaled with the depth assert [u.unit_id for u in out.results] == ["c2", "c3"] + if budget: + assert out.tokens_returned <= budget + else: + assert all(u.body and not u.elided for u in out.results) assert out.route == "hybrid+page_fallback" assert out.as_of["page_fallback"] == "pool_not_found" and out.as_of["page_offset"] == 2 assert out.next_cursor == "n" diff --git a/tests/unit/test_code_search_token_budget.py b/tests/unit/test_code_search_token_budget.py new file mode 100644 index 0000000000..10122a2664 --- /dev/null +++ b/tests/unit/test_code_search_token_budget.py @@ -0,0 +1,75 @@ +"""Code search has no token cap unless the deployment or request supplies one.""" + +from __future__ import annotations + +import pytest +from pydantic import ValidationError + +from server.code.api.models_search import CodeSearchInput +from server.code.app.search.shared import page_plan +from server.code.domain.units import ( + CodeUnit, + budget_units, + estimate_unit_tokens, + remaining_token_budget, +) +from server.settings import Settings, settings +from server.transport.mcp_defaults import mcp_default_arguments + + +def test_unlimited_keeps_every_whole_body_and_counts_tokens() -> None: + units = [CodeUnit(unit_id=str(i), path=f"src/{i}.py", body="x " * 20000) for i in range(5)] + served, used = budget_units(units, 0) + assert served == units and all(not u.elided for u in served) + assert used == sum(estimate_unit_tokens(u) for u in units) + assert used > 12000 + + +def test_unlimited_still_honours_bodyless_mode() -> None: + units = [CodeUnit(path=f"src/{i}.py", body="x " * 20000) for i in range(25)] + served, used = budget_units(units, 0, bodies="none") + assert len(served) == len(units) + assert all(u.elided and u.body == "" for u in served) + assert used == sum(estimate_unit_tokens(u) for u in served) + + +def test_fanout_uses_the_same_unlimited_budget(monkeypatch: pytest.MonkeyPatch) -> None: + from server.code.app.search_fanout import budget + + monkeypatch.setattr(settings, "code_search_token_budget", 0) + units = [CodeUnit(path=f"src/{i}.py", body="x " * 20000) for i in range(5)] + served, used = budget(units, CodeSearchInput(query="retry transport", bodies="auto")) + assert served == units and used > 12000 + monkeypatch.setattr(settings, "code_search_token_budget", 500) + served, used = budget(units, CodeSearchInput(query="retry transport", bodies="auto")) + assert used <= 500 and all(u.elided for u in served) + + +@pytest.mark.parametrize("overhead", [0, 300, 5000]) +def test_overhead_preserves_unlimited_and_never_turns_finite_into_unlimited(overhead: int) -> None: + assert remaining_token_budget(0, overhead) == 0 + assert remaining_token_budget(300, overhead) == max(1, 300 - overhead) + + +def test_environment_budget_applies_to_http_and_mcp(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("LOOM_CODE_SEARCH_TOKEN_BUDGET", "20000") + configured = Settings() + assert configured.code_search_token_budget == 20000 + monkeypatch.setattr(settings, "code_search_token_budget", configured.code_search_token_budget) + for args in ({"query": "how are requests retried"}, {"query": "RetryHandler::run"}): + for supplied in (args, mcp_default_arguments("code.search", args)): + assert page_plan(CodeSearchInput.model_validate(supplied)).token_budget == 20000 + assert page_plan(CodeSearchInput(query="retry", token_budget=0)).token_budget == 0 + assert page_plan(CodeSearchInput(query="retry", token_budget=500)).token_budget == 500 + + +def test_default_is_unlimited_and_negative_budgets_are_refused( + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.delenv("LOOM_CODE_SEARCH_TOKEN_BUDGET", raising=False) + assert Settings().code_search_token_budget == 0 + with pytest.raises(ValidationError): + CodeSearchInput(query="retry", token_budget=-1) + monkeypatch.setenv("LOOM_CODE_SEARCH_TOKEN_BUDGET", "-1") + with pytest.raises(ValidationError): + Settings() diff --git a/tests/unit/test_mcp_defaults.py b/tests/unit/test_mcp_defaults.py index 8bac94f6b0..40473cd837 100644 --- a/tests/unit/test_mcp_defaults.py +++ b/tests/unit/test_mcp_defaults.py @@ -1,5 +1,5 @@ -"""Over MCP, code.index_status defaults to the brief answer and code.search to a -1,500-token budget; HTTP keeps the ops' own defaults.""" +"""MCP defaults keep index status brief and code search bodyless, while +code search shares HTTP's deployment token budget.""" from __future__ import annotations @@ -20,10 +20,10 @@ def test_index_status_is_brief_over_mcp_unless_asked_otherwise() -> None: ) -def test_code_search_answers_within_1500_tokens_over_mcp_unless_asked_otherwise() -> None: +def test_code_search_uses_the_deployment_token_budget_over_mcp() -> None: from server.code.api.models_search import CodeSearchInput - assert mcp_default_arguments("code.search", {"query": "x"})["token_budget"] == 1500 + assert "token_budget" not in mcp_default_arguments("code.search", {"query": "x"}) assert ( mcp_default_arguments("code.search", {"query": "x", "token_budget": 4000})["token_budget"] == 4000 From 0714830084c6e0d1236a1a5c9e3b3ccaea95575b Mon Sep 17 00:00:00 2001 From: Lareb Zafar Date: Sat, 21 Nov 2026 18:01:21 +0530 Subject: [PATCH 2/8] Small search budgets keep results before optional annotations Skip risk annotations when their reservation would leave less than the result-head allowance. Cover finite request and deployment budgets, cursor pages, and the annotation threshold. Signed-off-by: Lareb Zafar --- docs/features/code-index/operations.md | 1 + server/code/app/search/shared.py | 7 ++++++- .../integration/test_code_search_token_budget.py | 9 +++++---- tests/unit/test_code_search_cursor.py | 16 ++++++++++++++++ tests/unit/test_code_search_token_budget.py | 10 ++++++++++ 5 files changed, 38 insertions(+), 5 deletions(-) diff --git a/docs/features/code-index/operations.md b/docs/features/code-index/operations.md index 3d81a124d9..8e4d933830 100644 --- a/docs/features/code-index/operations.md +++ b/docs/features/code-index/operations.md @@ -135,6 +135,7 @@ located = await agent.code.enclosing(["src/quota/limiter.py:88", "src/api/routes `token_budget: 0` for an unlimited response. This applies to HTTP and MCP, cursor pages and searches across repositories. `top_k` still limits the number of results per page, and `bodies: "none"` still returns pointers without code bodies (the MCP default). +Small finite budgets prioritize result heads over optional risk annotations. For a Compose installation, put the variable in the `.env` file beside `compose.yaml` and recreate the server container after changing it. diff --git a/server/code/app/search/shared.py b/server/code/app/search/shared.py index 08fa979296..16446423ee 100644 --- a/server/code/app/search/shared.py +++ b/server/code/app/search/shared.py @@ -51,11 +51,16 @@ def page_plan(inp: Any) -> PagePlan: inp.token_budget if inp.token_budget is not None else _settings.code_search_token_budget ) annotate = bool(inp.annotate and _settings.code_risk_annotations) + reserve = code_risk.reserve_for(inp.top_k) if annotate else 0 + # Result heads take priority when a finite budget cannot fund annotations too. + if annotate and token_budget and token_budget < reserve + 200: + annotate = False + reserve = 0 return PagePlan( token_budget=token_budget, bodies=inp.bodies or _settings.code_search_bodies_default, annotate=annotate, - reserve=code_risk.reserve_for(inp.top_k) if annotate else 0, + reserve=reserve, ) diff --git a/tests/integration/test_code_search_token_budget.py b/tests/integration/test_code_search_token_budget.py index a49196f5e6..b48d6f01ba 100644 --- a/tests/integration/test_code_search_token_budget.py +++ b/tests/integration/test_code_search_token_budget.py @@ -74,10 +74,11 @@ async def test_search_keeps_full_bodies_unless_a_budget_is_supplied( assert unlimited.tokens_returned > 3000 assert all(u.body and not u.elided for u in unlimited.results) - monkeypatch.setattr(settings, "code_search_token_budget", 1000) - bounded = await handle_code_search(request) - assert bounded.tokens_returned <= 1000 - assert any(u.elided for u in bounded.results) + for budget in (300, 1000): + monkeypatch.setattr(settings, "code_search_token_budget", budget) + bounded = await handle_code_search(request) + assert bounded.results and bounded.tokens_returned <= budget + assert any(u.elided for u in bounded.results) for budget in (0, 20000): overridden = await handle_code_search(request.model_copy(update={"token_budget": budget})) assert [u.body for u in overridden.results] == [u.body for u in unlimited.results] diff --git a/tests/unit/test_code_search_cursor.py b/tests/unit/test_code_search_cursor.py index 7c716532f3..ef87699abe 100644 --- a/tests/unit/test_code_search_cursor.py +++ b/tests/unit/test_code_search_cursor.py @@ -293,6 +293,22 @@ def test_last_page_has_no_cursor(monkeypatch: pytest.MonkeyPatch) -> None: assert not out.has_more and out.next_cursor == "" and "page_stale" not in out.as_of +@pytest.mark.parametrize("budget,top_k", [(300, 5), (500, 10)]) +@pytest.mark.parametrize("use_default", [False, True]) +def test_small_page_budget_keeps_results_before_optional_annotations( + monkeypatch: pytest.MonkeyPatch, budget: int, top_k: int, use_default: bool +) -> None: + monkeypatch.setattr(settings, "code_risk_annotations", True) + monkeypatch.setattr(settings, "code_search_token_budget", budget if use_default else 0) + inp = _inp(top_k=top_k, token_budget=None if use_default else budget) + cursor = paging.encode(kind="s", run_id="r", offset=1, params=_ph(inp), indexed_commit="") + row = {"payload": _payload(12), "indexed_commit": "", "created_at": None} + _drive(monkeypatch, inp, row) + out = asyncio.run(h.handle_code_search(inp.model_copy(update={"cursor": cursor}))) + assert out.results and not out.abstain + assert out.tokens_returned <= budget + + @pytest.mark.parametrize("default", [0, 2400]) def test_page_plan_uses_the_deployment_budget_and_honours_the_request( monkeypatch: pytest.MonkeyPatch, default: int diff --git a/tests/unit/test_code_search_token_budget.py b/tests/unit/test_code_search_token_budget.py index 10122a2664..96f60700a6 100644 --- a/tests/unit/test_code_search_token_budget.py +++ b/tests/unit/test_code_search_token_budget.py @@ -73,3 +73,13 @@ def test_default_is_unlimited_and_negative_budgets_are_refused( monkeypatch.setenv("LOOM_CODE_SEARCH_TOKEN_BUDGET", "-1") with pytest.raises(ValidationError): Settings() + + +@pytest.mark.parametrize("budget,annotate", [(0, True), (300, False), (539, False), (540, True)]) +def test_annotations_leave_room_for_results( + monkeypatch: pytest.MonkeyPatch, budget: int, annotate: bool +) -> None: + monkeypatch.setattr(settings, "code_risk_annotations", True) + plan = page_plan(CodeSearchInput(query="retry transport", top_k=5, token_budget=budget)) + assert plan.annotate is annotate + assert bool(plan.reserve) is annotate From 8e41f5715c8de10b24a13b122b6efb04b0523ed2 Mon Sep 17 00:00:00 2001 From: Lareb Zafar Date: Sat, 21 Nov 2026 18:05:34 +0530 Subject: [PATCH 3/8] Code skill documents optional search token budgets Signed-off-by: Lareb Zafar --- skills/loom-code/SKILL.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/skills/loom-code/SKILL.md b/skills/loom-code/SKILL.md index d14e731250..090a21fe8d 100644 --- a/skills/loom-code/SKILL.md +++ b/skills/loom-code/SKILL.md @@ -54,8 +54,9 @@ read is one function instead of one file. Reading the whole file after a ## Budgets -Every op takes `token_budget`. Defaults are tuned per op (search 4k, -context_pack 2.5k, impact 3k). Ask for `bodies: "none"` on the first call +`code.search` has no token cap by default. `LOOM_CODE_SEARCH_TOKEN_BUDGET` +sets a deployment default; an explicit `token_budget` overrides it, and `0` +means unlimited. Other ops keep their own defaults. Ask for `bodies: "none"` on the first call and expand one unit rather than raising the budget. `code.ask` returns a grounded prose answer with citations; use it for "how does X work" questions, not for locating code. From d04d948ba2154fe179ccd60d688c0063c854786b Mon Sep 17 00:00:00 2001 From: Lareb Zafar Date: Sat, 21 Nov 2026 18:08:40 +0530 Subject: [PATCH 4/8] SDK search docs describe deployment budget defaults Signed-off-by: Lareb Zafar --- sdk/python/loom/code.py | 4 ++-- tests/unit/test_sdk_default_drift.py | 3 +-- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/sdk/python/loom/code.py b/sdk/python/loom/code.py index 97274a2168..00536fd860 100644 --- a/sdk/python/loom/code.py +++ b/sdk/python/loom/code.py @@ -66,8 +66,8 @@ async def search( `retrieval_risk`, and `as_of.stale` (index trails master by more than the configured commits — treat spans as approximate). Keep `trace_run_id` and call `outcome(...)`. `token_budget` / `bodies` - unset take the server's defaults (a route-aware budget, the - deployment's bodies setting); `bodies="none"` returns + unset take the deployment's budget and bodies settings; + `bodies="none"` returns spans and signatures only (cheapest); `annotate=False` drops the churn/amp/tested risk annotations. `pattern` (literal, or RE2 with `regex=True`) constrains BOTH legs to chunks containing it — one call diff --git a/tests/unit/test_sdk_default_drift.py b/tests/unit/test_sdk_default_drift.py index 283a619081..bce021d8f3 100644 --- a/tests/unit/test_sdk_default_drift.py +++ b/tests/unit/test_sdk_default_drift.py @@ -1,7 +1,6 @@ """A value the SDK's domain clients put on the wire by default equals the server Input model's default for that field, so an unset SDK kwarg never -overrides what the server would choose (a route-aware budget, a deployment -setting). Each client method is called with only its required arguments +overrides the deployment's settings. Each client method is called with only its required arguments against a recording transport; a server field without a default is skipped (there is nothing to drift from).""" From b580ffd4986feecbbe72d98a5d805c9335755869 Mon Sep 17 00:00:00 2001 From: Lareb Zafar Date: Sun, 22 Nov 2026 13:44:38 +0530 Subject: [PATCH 5/8] Code retrieval defaults to unlimited context Let callers choose response caps for their repository. Preserve whole retained definitions and selected lessons by default, and fit search history within explicit finite caps. Signed-off-by: Lareb Zafar --- docs/features/code-index/history-and-prs.md | 2 +- docs/features/code-index/operations.md | 17 ++++ docs/reference/configuration.md | 12 ++- docs/reference/operations/code.md | 14 ++-- loom.example.yaml | 16 ++-- schemas/loom-settings.schema.json | 26 +++--- sdk/python/loom/code.py | 12 +-- sdk/python/loom/code_tools.py | 3 +- sdk/typescript/src/code-tools.test.ts | 4 +- sdk/typescript/src/code-tools.ts | 3 +- server/code/api/models_context.py | 9 +-- server/code/api/models_navigation.py | 13 ++- server/code/api/models_review.py | 6 +- server/code/api/models_search.py | 2 +- server/code/api/models_symbol.py | 5 +- server/code/app/answers_entry.py | 6 +- server/code/app/ask.py | 4 +- server/code/app/context.py | 13 ++- server/code/app/history.py | 12 +++ server/code/app/index/packs.py | 6 +- server/code/app/index/review_brief.py | 13 +-- server/code/app/index/task_pack.py | 2 +- server/code/app/review_brief.py | 2 +- server/code/app/search/handler.py | 9 ++- server/code/app/search/history.py | 4 +- server/code/app/search/pipeline.py | 1 + server/code/app/search/serve.py | 8 +- server/code/app/symbol/enclosing.py | 2 +- server/code/app/symbol/outline.py | 4 +- server/code/app/symbol/resolve.py | 4 +- server/code/app/symbol/symbol.py | 13 ++- server/code/domain/symbol_body.py | 4 +- server/knowledge/app/repo_docs.py | 4 +- server/memory/app/path_lessons.py | 4 +- server/settings/_history.py | 40 ++++++++++ server/settings/catalog.py | 18 ++--- .../test_code_search_token_budget.py | 64 +++++++++++++++ tests/unit/test_code_enclosing.py | 12 +++ tests/unit/test_code_result_lessons.py | 9 +++ tests/unit/test_code_review_brief_sections.py | 4 +- .../test_code_symbol_body_completeness.py | 11 ++- tests/unit/test_sdk_code_tools.py | 4 +- tests/unit/test_unlimited_code_context.py | 80 +++++++++++++++++++ 43 files changed, 372 insertions(+), 129 deletions(-) create mode 100644 tests/unit/test_unlimited_code_context.py diff --git a/docs/features/code-index/history-and-prs.md b/docs/features/code-index/history-and-prs.md index a68506ba21..81908e1104 100644 --- a/docs/features/code-index/history-and-prs.md +++ b/docs/features/code-index/history-and-prs.md @@ -84,7 +84,7 @@ first `LOOM_CODE_REVIEW_BRIEF_RATIONALE_PATHS` (10) changed files, source files those the brief stores, and keeps at most `LOOM_CODE_REVIEW_BRIEF_RATIONALE_ROWS` (8) rows, those with something to check first. It serves whole rows, `check` rows first and then constraints, up to `LOOM_CODE_REVIEW_BRIEF_RATIONALE_TOKENS` (250) tokens, and always -the first row; the tier's budget may still trim the section like any other. Each row +the first row; an explicit token budget may still trim the section like any other. Each row carries the pre-edit block's line for it with its value cut at the line length (source, `(pinned)` and the code-change note kept), `pinned`, `code_state` and a `verdict`. Each changed file read is one `memory.for_file` read: four ClickHouse reads (files match, code diff --git a/docs/features/code-index/operations.md b/docs/features/code-index/operations.md index 8e4d933830..6124791bc5 100644 --- a/docs/features/code-index/operations.md +++ b/docs/features/code-index/operations.md @@ -345,3 +345,20 @@ Adding, branching, restricting and removing repositories (`code.repo.add`, - [history-and-prs.md](history-and-prs.md) — the PR plane, bisect, backports - [Python SDK reference](../../reference/python-sdk.md), [MCP reference](../../reference/mcp.md) - [operations reference](../../reference/operations.md#code) — generated arguments + +### Response token limits + +Code retrieval returns selected context without an implicit token cap. `code.symbol`, +`code.enclosing`, `code.outline`, `code.trace`, `code.context_pack`, `code.map` and +`code.review_brief` default `token_budget` to `0` (unlimited). A positive value opts +into a cap. Symbol lookups return complete retained bodies, including large containers; +explicitly capped container lookups can return a skeleton and member outline. + +`code.ask` uses `code_ask_token_budget` when the request omits a budget; the setting +defaults to `0`. An explicit request value of `0` overrides a finite deployment cap. +Attached file lessons use `code_result_lessons_tokens`, also unlimited by default. +The internal code grounding reads for memory questions likewise default to no token cap. + +Result counts, requested body modes, access checks, source completeness checks and +execution deadlines still apply. Unlimited does not reconstruct source absent from the +index. Model generation limits are separate from retrieval context limits. diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 99d60f8d3e..3481ddd843 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -44,6 +44,10 @@ Every change to a setting's default, from `server/settings/_history.py`. A deplo | Release | Variable | Was | Is | Why | | --- | --- | --- | --- | --- | +| 1.3.1 | `LOOM_MEMORY_ASK_CODE_SEARCH_TOKEN_BUDGET` | `1400` | `0` | Return selected retrieval context without an implicit token cap; positive values opt in to a cap. | +| 1.3.1 | `LOOM_MEMORY_ASK_CODE_SYMBOL_TOKEN_BUDGET` | `400` | `0` | Return selected retrieval context without an implicit token cap; positive values opt in to a cap. | +| 1.3.1 | `LOOM_CODE_RESULT_LESSONS_TOKENS` | `250` | `0` | Return selected retrieval context without an implicit token cap; positive values opt in to a cap. | +| 1.3.1 | `LOOM_CODE_ASK_TOKEN_BUDGET` | `4000` | `0` | Return selected retrieval context without an implicit token cap; positive values opt in to a cap. | | 1.3.1 | `LOOM_MCP_ALWAYS_LOAD_TOOLS` | `'code.search,code.symbol'` | `''` | Leave tool loading to the host so sessions do not need unused code schemas upfront. Set an explicit operation list to request eager loading. | | 1.2.0 | `LOOM_KNOWLEDGE_INGEST_INTERVAL_SECONDS` | `2` | `0` | The ingest worker takes the next job as soon as one ends instead of waiting 2 s after every job, so a queue of small documents drains at the speed of its jobs; a pass that finds no job still waits `LOOM_KNOWLEDGE_INGEST_IDLE_INTERVAL_SECONDS`. | | 1.2.0 | `LOOM_CLICKSTACK_USER_ID_KEYS` | `'user_id,user.id,enduser.id'` | `'user_id,user.id,enduser.id,loom.user_id,langfuse.user.id'` | A user-scoped ClickStack erasure also matches the user-id keys Loom's own child spans carry, so they are erased with the request span. A deployment that sets the variable keeps its own list and should add both keys. | @@ -242,7 +246,7 @@ The code plane: ingest, indexes, search, ask, review. | --- | --- | --- | --- | --- | | `LOOM_CODE_INTEL_ENABLED` | `bool` | `True` | | Master kill switch, checked at the top of every code.* handler but the retirement (code.repo.remove), which only deletes. | | `LOOM_CODE_TEST_GATE_RUN_TEMPLATES` | `str` | `''` | | code.test_gate run recipes (LOOM_CODE_TEST_GATE_RUN_TEMPLATES): JSON list of {"pattern": , "run":