diff --git a/docs/architecture/code-index-architecture.md b/docs/architecture/code-index-architecture.md index bddfb39c25..1f66d3bcb0 100644 --- a/docs/architecture/code-index-architecture.md +++ b/docs/architecture/code-index-architecture.md @@ -351,6 +351,11 @@ the matched files. Lessons are read after cached match data, within the request' remaining deadline. Presence queries and uncovered paths carry none; `include_lessons=false` skips the read. +`code.enclosing` carries the same file lessons for resolved locations. Repeated +locations share one file read; unresolved locations bring no lessons. The caller's +readable memory namespaces, narrowed-token refusal, timeout and token cap apply +through the shared result enrichment. Empty lesson fields stay off the wire. + Search and grep rank candidate lessons across all selected files by query-term overlap after constraints and pinned rows. English inflections share stems; equal matches keep path order, then the listing's confidence and recency order. diff --git a/docs/reference/operations/code.md b/docs/reference/operations/code.md index 7f1fdc1cc4..25f8d2e55f 100644 --- a/docs/reference/operations/code.md +++ b/docs/reference/operations/code.md @@ -583,6 +583,8 @@ Batched `path:line` -> enclosing function. | Input field | Type | Default | Meaning | | --- | --- | --- | --- | +| `include_lessons` | `bool` | `True` | Attach `lessons`: the memories about the answer's top files (for code.context_pack, a `task` briefing's only). | +| `lesson_namespaces` | `list[str]` | *(computed)* | The memory namespaces `lessons` reads besides the repository's team rules (over MCP the caller's memory home, filled in); one the caller cannot read is skipped. | | `org` | `str` | `''` | The tenant (first element of the identity tuple). | | `namespace` | `str` | `''` | The namespace the op reads or writes. | | `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. | @@ -596,6 +598,8 @@ Batched `path:line` -> enclosing function. | Output field | Type | Meaning | | --- | --- | --- | +| `lessons` | `list[dict[str, Any]]` | The memories about the answer's top files, best first, capped at `code_result_lessons_tokens`; each row {path, memory_key, namespace, excerpt, code_state}, with `changed_since` and `supersedes_key` when they apply. | +| `lessons_left_out` | `int` | How many rows about those files the lessons' token cap or a cut left out, with the rows another row read for the answer supersedes. | | `results` | `list[dict[str, Any]]` | one entry per input location, input order preserved: {path, line, symbol, symbol_id, qualified_name, signature, tier, kind, start_line, end_line} kind is "function" / "method" / "fixture" for a line inside a function body; "class"… | | `resolved` | `int` | Locations that landed inside a function, type, or document section. | | `paths_indexed` | `int` | distinct input paths that have any symbol rows | diff --git a/sdk/python/loom/ops.py b/sdk/python/loom/ops.py index 036811d7d9..5296dde77a 100644 --- a/sdk/python/loom/ops.py +++ b/sdk/python/loom/ops.py @@ -6376,6 +6376,8 @@ class CodeCoverageClaimOutput(TypedDict, total=False): class CodeEnclosingInput(TypedDict, total=False): "Batched `path:line` -> enclosing function. Built for the grep shim:" + include_lessons: NotRequired[bool] + lesson_namespaces: NotRequired[list[str]] org: NotRequired[str] namespace: NotRequired[str] agent: NotRequired[str] @@ -6391,6 +6393,8 @@ class CodeEnclosingInput(TypedDict, total=False): class CodeEnclosingBody(TypedDict, total=False): "Batched `path:line` -> enclosing function. Built for the grep shim:" + include_lessons: NotRequired[bool] + lesson_namespaces: NotRequired[list[str]] org: NotRequired[str] namespace: NotRequired[str] agent: NotRequired[str] @@ -6404,6 +6408,8 @@ class CodeEnclosingBody(TypedDict, total=False): class CodeEnclosingOutput(TypedDict, total=False): + lessons: NotRequired[list[dict[str, Any]]] + lessons_left_out: NotRequired[int] results: Required[list[dict[str, Any]]] resolved: Required[int] paths_indexed: Required[int] diff --git a/sdk/typescript/src/generated/ops.ts b/sdk/typescript/src/generated/ops.ts index c88b34f554..406d999707 100644 --- a/sdk/typescript/src/generated/ops.ts +++ b/sdk/typescript/src/generated/ops.ts @@ -761,6 +761,8 @@ export interface CodeCoverageClaimOutput { } export interface CodeEnclosingInput { + include_lessons?: boolean; + lesson_namespaces?: string[]; org?: string; namespace?: string; agent?: string; @@ -774,6 +776,8 @@ export interface CodeEnclosingInput { } export interface CodeEnclosingOutput { + lessons?: Array>; + lessons_left_out?: number; results: Array>; resolved: number; paths_indexed: number; diff --git a/server/code/api/models_navigation.py b/server/code/api/models_navigation.py index e4f79cf124..2255882a00 100644 --- a/server/code/api/models_navigation.py +++ b/server/code/api/models_navigation.py @@ -116,7 +116,7 @@ def _drop_empty_head(self, handler: SerializerFunctionWrapHandler) -> dict[str, # ============================================================ -class CodeEnclosingInput(_CodeIdentity): +class CodeEnclosingInput(_CodeIdentity, _ResultLessons): """Batched `path:line` -> enclosing function. Built for the grep shim: real grep stays exact, then ONE round-trip names the function every hit sits in — the "which function is this line in?" question that otherwise @@ -146,7 +146,7 @@ class CodeEnclosingInput(_CodeIdentity): neighbour_k: int = Field(default=5, ge=1, le=20) -class CodeEnclosingOutput(BaseModel): +class CodeEnclosingOutput(_LessonsOut): # one entry per input location, input order preserved: # {path, line, symbol, symbol_id, qualified_name, signature, tier, kind, # start_line, end_line} diff --git a/server/code/api/ops.py b/server/code/api/ops.py index c99098b611..3ffde91182 100644 --- a/server/code/api/ops.py +++ b/server/code/api/ops.py @@ -385,7 +385,7 @@ session_content=True, input_model=CodeEnclosingInput, output_model=CodeEnclosingOutput, - handler=handle_code_enclosing, + handler=result_lessons.WithLessons(handle_code_enclosing, result_lessons.enclosing_paths), idempotent=True, required_role=Role.VIEWER, ), diff --git a/server/code/app/result_lessons.py b/server/code/app/result_lessons.py index 3298c4f142..dc66670453 100644 --- a/server/code/app/result_lessons.py +++ b/server/code/app/result_lessons.py @@ -162,6 +162,11 @@ def outline_paths(_input: Any, out: Any) -> list[str]: return [out.path] +def enclosing_paths(_input: Any, out: Any) -> list[str]: + # Unresolved locations are echoed by the handler; they are not indexed evidence. + return [str(row.get("path") or "") for row in out.results if row.get("start_line")] + + def pack_paths(_input: Any, out: Any) -> list[str]: # a task briefing's files; the orientation map and a PR's stored pack name none return list(out._paths) diff --git a/server/identity/domain/read_scope.py b/server/identity/domain/read_scope.py index 81ad71df69..9f124f94cf 100644 --- a/server/identity/domain/read_scope.py +++ b/server/identity/domain/read_scope.py @@ -349,7 +349,7 @@ def pin_read_filters[M: BaseModel](input: M, auth: Any) -> tuple[M, bool]: "code.coverage.unwatch": _CODE_INDEX, "code.coverage.watch": _CODE_INDEX, "code.coverage_claim": _CODE_INDEX, - "code.enclosing": _CODE_INDEX, + "code.enclosing": _CODE_LESSONS, "code.examples": _CODE_INDEX, "code.files": _CODE_INDEX, "code.first_build": _CODE_INDEX, diff --git a/tests/integration/test_code_result_lessons.py b/tests/integration/test_code_result_lessons.py index 10ebd155a9..0a3a4eb52d 100644 --- a/tests/integration/test_code_result_lessons.py +++ b/tests/integration/test_code_result_lessons.py @@ -94,6 +94,54 @@ async def test_grep_attaches_requested_file_lessons_and_respects_opt_out( assert "lessons" not in payload.get("data", payload) +async def test_enclosing_attaches_only_authorized_resolved_file_lessons( + control_plane_url: str, mint_test_token: Any, ch_client: Any +) -> None: + org = unique_org("enclosing-lessons") + writer = mint_test_token(org=org, namespaces=["*"], roles=["writer"]) + _set(org, control_plane_url, writer, "notes/allowed", "Keep callback order.", [PATH]) + _set(org, control_plane_url, writer, "notes/missing", "Unresolved file note.", ["absent.py"]) + ch_client.insert( + "loom.code_symbols", + [[org, "code", "treesitter", "pkg::run", "run-id", "run", "function", PATH, 1, 5]], + column_names=[ + "org", + "namespace", + "tier", + "qualified_name", + "symbol_id", + "name", + "kind", + "path", + "start_line", + "end_line", + ], + ) + body = dict( + org=org, + namespace="code", + locations=[f"{PATH}:2", f"{PATH}:3", "absent.py:1"], + lesson_namespaces=["dev"], + ) + for names, include in [(["code", "dev"], True), (["code", "dev"], False), (["code"], True)]: + reader = mint_test_token(org=org, namespaces=names, roles=["viewer"]) + async with httpx.AsyncClient( + base_url=control_plane_url, headers={"Authorization": f"Bearer {reader}"}, timeout=10 + ) as client: + response = await client.post( + "/v1/code.enclosing", json={**body, "include_lessons": include} + ) + assert response.status_code == 200, response.text + payload = response.json() + data = payload.get("data", payload) + assert data["resolved"] == 2 and len(data["results"]) == 3 + if include and "dev" in names: + assert [row["memory_key"] for row in data["lessons"]] == ["notes/allowed"] + assert data["lessons"][0]["path"] == PATH + else: + assert "lessons" not in data + + async def test_lessons_match_the_result_file_by_path( control_plane_url: str, mint_test_token: Any, ch_client: Any ) -> None: diff --git a/tests/unit/test_code_result_lessons.py b/tests/unit/test_code_result_lessons.py index 6a8c9010e8..31692e31d6 100644 --- a/tests/unit/test_code_result_lessons.py +++ b/tests/unit/test_code_result_lessons.py @@ -12,7 +12,12 @@ import pytest from server.code.api.models_grep import CodeGrepInput, CodeGrepOutput -from server.code.api.models_navigation import CodeOutlineInput, CodeOutlineOutput +from server.code.api.models_navigation import ( + CodeEnclosingInput, + CodeEnclosingOutput, + CodeOutlineInput, + CodeOutlineOutput, +) from server.code.api.models_search import CodeSearchInput, CodeSearchOutput from server.code.app import result_lessons, search_memo from server.memory.app import code_plane_reads, path_lessons @@ -615,6 +620,7 @@ async def _outline(inp: CodeOutlineInput) -> CodeOutlineOutput: "code.callees", "code.impact", "code.outline", + "code.enclosing", "code.context_pack", ], ) @@ -692,6 +698,7 @@ def test_every_code_result_op_is_wrapped_with_its_files() -> None: from server.code.app.context import handle_code_context_pack from server.code.app.grep import handle_code_grep from server.code.app.search.handler import handle_code_search + from server.code.app.symbol.enclosing import handle_code_enclosing from server.code.app.symbol.graph import handle_code_callees, handle_code_callers from server.code.app.symbol.impact import handle_code_impact from server.code.app.symbol.outline import handle_code_outline @@ -703,6 +710,7 @@ def test_every_code_result_op_is_wrapped_with_its_files() -> None: "code.callees": (handle_code_callees, result_lessons.edge_paths), "code.impact": (handle_code_impact, result_lessons.impact_paths), "code.outline": (handle_code_outline, result_lessons.outline_paths), + "code.enclosing": (handle_code_enclosing, result_lessons.enclosing_paths), "code.context_pack": (handle_code_context_pack, result_lessons.pack_paths), } for name, (inner, paths_of) in wanted.items(): @@ -748,6 +756,50 @@ def test_grep_presence_and_uncovered_paths_have_no_lessons(): ] +@pytest.mark.asyncio +@pytest.mark.parametrize("skip", ["none", "argument", "narrowed", "unresolved"]) +async def test_enclosing_lessons_follow_only_resolved_files( + monkeypatch: pytest.MonkeyPatch, skip: str +) -> None: + calls: list[dict[str, Any]] = [] + _stub_reads(monkeypatch, ["mem-home", "code-repo"], calls) + monkeypatch.setattr( + "server.identity.app.request_scope.request_narrowed", lambda: skip == "narrowed" + ) + + async def enclosing(inp: CodeEnclosingInput) -> CodeEnclosingOutput: + resolved = skip != "unresolved" + return CodeEnclosingOutput( + results=[ + {"path": "src/a.py", "start_line": 1 if resolved else 0, "end_line": 5}, + {"path": "src/a.py", "start_line": 2 if resolved else 0, "end_line": 5}, + {"path": "missing.py", "start_line": 0, "end_line": 0}, + ], + resolved=2 if resolved else 0, + paths_indexed=1, + paths_total=2, + took_ms=0, + ) + + wrapped = result_lessons.WithLessons(enclosing, result_lessons.enclosing_paths) + out = await wrapped( + CodeEnclosingInput( + org="acme", + namespace="code-repo", + locations=["src/a.py:2", "src/a.py:3", "missing.py:1"], + lesson_namespaces=["mem-home", "denied"], + include_lessons=skip != "argument", + ) + ) + assert len(out.results) == 3 + if skip != "none": + assert calls == [] and "lessons" not in out.model_dump() + else: + assert calls[0]["paths"] == ["src/a.py"] + assert calls[0]["nss"] == ["mem-home", "code-repo"] + assert out.lessons[0]["namespace"] == "mem-home" + + def test_grep_enrichment_uses_only_the_remaining_deadline(monkeypatch: pytest.MonkeyPatch): from types import SimpleNamespace diff --git a/tests/unit/test_op_scope_fields.py b/tests/unit/test_op_scope_fields.py index 77fb263a0f..8b756d2e51 100644 --- a/tests/unit/test_op_scope_fields.py +++ b/tests/unit/test_op_scope_fields.py @@ -46,6 +46,7 @@ ("code.symbol", "namespaces"): _FANOUT, ("code.grep", "namespaces"): _FANOUT, ("code.grep", "lesson_namespaces"): "server.memory.app.code_plane_reads.lesson_namespaces", + ("code.enclosing", "lesson_namespaces"): "server.memory.app.code_plane_reads.lesson_namespaces", ("code.symbol", "lesson_namespaces"): "server.memory.app.code_plane_reads.lesson_namespaces", ("code.callees", "lesson_namespaces"): "server.memory.app.code_plane_reads.lesson_namespaces", ("code.callers", "lesson_namespaces"): "server.memory.app.code_plane_reads.lesson_namespaces",