nooa-cli 0.0.9__tar.gz → 0.0.10__tar.gz

{nooa_cli-0.0.9 → nooa_cli-0.0.10}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: nooa-cli
-Version: 0.0.9
+Version: 0.0.10
 Summary: CLI for nemo-oo-agents (`nooa` command: eval runner, trace viewer, config)
 Project-URL: Homepage, https://github.com/NVIDIA-NeMo/labs-OO-Agents
 Project-URL: Repository, https://github.com/NVIDIA-NeMo/labs-OO-Agents
@@ -44,9 +44,19 @@ uv add "nooa-cli[datascience]"
 
 ```bash
 nooa --help
-nooa start-dev            # launch the trace viewer
-nooa eval ...             # eval pipeline runner
-nooa traces ...           # inspect/manage trace files
+nooa start-dev        # launch the trace viewer
+nooa eval ...         # eval pipeline runner
+nooa traces ...       # inspect/manage trace files
+```
+
+Install the separate `nooa-acp` package to add the `nooa acp` plugin command and
+run the NOOA coding agent from an ACP-compatible client:
+
+```bash
+uv add nooa-acp
+export NOOA_MODEL=nvidia_nim/nvidia/nemotron-3-super-120b-a12b
+export NVIDIA_API_KEY=nvapi-...
+uv run nooa-acp
 ```
 
 See the main repo [README](https://github.com/NVIDIA-NeMo/labs-OO-Agents/blob/main/README.md) for the framework documentation.

{nooa_cli-0.0.9 → nooa_cli-0.0.10}/README.md

@@ -17,9 +17,19 @@ uv add "nooa-cli[datascience]"
 
 ```bash
 nooa --help
-nooa start-dev            # launch the trace viewer
-nooa eval ...             # eval pipeline runner
-nooa traces ...           # inspect/manage trace files
+nooa start-dev        # launch the trace viewer
+nooa eval ...         # eval pipeline runner
+nooa traces ...       # inspect/manage trace files
+```
+
+Install the separate `nooa-acp` package to add the `nooa acp` plugin command and
+run the NOOA coding agent from an ACP-compatible client:
+
+```bash
+uv add nooa-acp
+export NOOA_MODEL=nvidia_nim/nvidia/nemotron-3-super-120b-a12b
+export NVIDIA_API_KEY=nvapi-...
+uv run nooa-acp
 ```
 
 See the main repo [README](https://github.com/NVIDIA-NeMo/labs-OO-Agents/blob/main/README.md) for the framework documentation.

{nooa_cli-0.0.9 → nooa_cli-0.0.10}/src/nooa_cli/coding/__init__.py

@@ -9,11 +9,24 @@ from nooa_cli.coding.activity import (
     TerminalCommandOutput,
     TerminalCommandStarted,
 )
+from nooa_cli.coding.agent import CodingAgent
+from nooa_cli.coding.instructions import (
+    discover_agent_instruction_files,
+    render_agent_instructions,
+)
+from nooa_cli.coding.settings import load_coding_skills_dirs
+from nooa_cli.coding.slash_commands import CodingSlashCommand, CodingSlashCommandRegistry
 
 __all__ = [
     "ActivityShellTools",
+    "CodingAgent",
+    "CodingSlashCommand",
+    "CodingSlashCommandRegistry",
     "FileEdit",
     "TerminalCommandFinished",
     "TerminalCommandOutput",
     "TerminalCommandStarted",
+    "discover_agent_instruction_files",
+    "load_coding_skills_dirs",
+    "render_agent_instructions",
 ]

{nooa_cli-0.0.9 → nooa_cli-0.0.10}/src/nooa_cli/coding/activity.py

@@ -4,7 +4,9 @@
 
 from __future__ import annotations
 
+import asyncio
 import logging
+import re
 from collections.abc import AsyncIterator
 from difflib import unified_diff
 from functools import wraps
@@ -27,6 +29,8 @@ logger = logging.getLogger(__name__)
 
 _MAX_EVENT_TEXT_CHARS = 10_000
 _MAX_COMMAND_OUTPUT_CHARS = 30_000
+_MAX_DIFF_INPUT_CHARS = 1_000_000
+_MAX_DIFF_INPUT_LINES = 20_000
 
 
 def _line_count(value: str) -> int:
@@ -35,23 +39,61 @@ def _line_count(value: str) -> int:
     return value.count("\n") + (0 if value.endswith("\n") else 1)
 
 
-def _edit_diff(path: str, old_text: str, new_text: str, start_line: int | None) -> str:
-    lines = list(
-        unified_diff(
-            old_text.splitlines(keepends=True),
-            new_text.splitlines(keepends=True),
-            fromfile=f"a/{path}",
-            tofile=f"b/{path}",
-        )
+def _diff_input_is_too_large(value: str) -> bool:
+    return len(value) > _MAX_DIFF_INPUT_CHARS or _line_count(value) > _MAX_DIFF_INPUT_LINES
+
+
+def _omitted_diff(path: str, reason: str) -> tuple[str, bool]:
+    return (
+        f"--- a/{path}\n+++ b/{path}\n@@ -0,0 +0,0 @@\n Diff omitted: {reason}.\n",
+        False,
     )
-    if start_line is not None:
-        for index, line in enumerate(lines):
-            if line.startswith("@@ "):
-                old_count = max(1, _line_count(old_text))
-                new_count = max(1, _line_count(new_text))
-                lines[index] = f"@@ -{start_line},{old_count} +{start_line},{new_count} @@\n"
-                break
-    return pformat("".join(lines), max_string=_MAX_EVENT_TEXT_CHARS, unquote_strings=True)
+
+
+_HUNK_HEADER = re.compile(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@(.*)$")
+
+
+def _offset_hunk_header(line: str, offset: int) -> str:
+    """Shift one hunk header into file coordinates, keeping difflib's counts."""
+    match = _HUNK_HEADER.match(line.rstrip("\n"))
+    if match is None:
+        return line
+    old_start, old_count, new_start, new_count, trailer = match.groups()
+    old_part = f"-{int(old_start) + offset}" + (f",{old_count}" if old_count else "")
+    new_part = f"+{int(new_start) + offset}" + (f",{new_count}" if new_count else "")
+    return f"@@ {old_part} {new_part} @@{trailer}\n"
+
+
+def _edit_diff(
+    path: str,
+    old_text: str,
+    new_text: str,
+    start_line: int | None,
+) -> tuple[str, bool]:
+    """Return a bounded, line-oriented unified diff and its completeness."""
+    if _diff_input_is_too_large(old_text) or _diff_input_is_too_large(new_text):
+        return _omitted_diff(path, "file content exceeds the safe diff preview limit")
+
+    output = TruncatingStringIO(limit=_MAX_EVENT_TEXT_CHARS)
+    # A region diff is generated in region coordinates; every hunk shifts by the
+    # same amount to reach file coordinates. Rewriting only the first one, with
+    # the whole region's counts, left later hunks region-relative — able to point
+    # before the first hunk, and unappliable by patch.
+    offset = start_line - 1 if start_line is not None else 0
+    for line in unified_diff(
+        old_text.splitlines(keepends=True),
+        new_text.splitlines(keepends=True),
+        fromfile=f"a/{path}",
+        tofile=f"b/{path}",
+    ):
+        if offset and line.startswith("@@ "):
+            line = _offset_hunk_header(line, offset)
+        if not line.endswith("\n"):
+            # difflib emits the source line verbatim, so unterminated content
+            # would run the next marker onto the same line ("-a+b").
+            line = f"{line}\n\\n"
+        output.write(line)
+    return output.getvalue(), not output.was_truncated
 
 
 class FileEdit(EventBase):  # type: ignore[misc]
@@ -82,6 +124,10 @@ class FileEdit(EventBase):  # type: ignore[misc]
         bool,
         Field(description="Whether old_text and new_text contain the complete affected text"),
     ] = True
+    diff_complete: Annotated[
+        bool,
+        Field(description="Whether diff contains the complete unified diff"),
+    ] = True
 
 
 class TerminalCommandStarted(EventBase):  # type: ignore[misc]
@@ -107,7 +153,11 @@ class TerminalCommandStarted(EventBase):  # type: ignore[misc]
 
 
 class TerminalCommandOutput(EventBase):  # type: ignore[misc]
-    """One streaming output chunk from a coding-agent terminal command."""
+    """The output of one coding-agent terminal command.
+
+    Emitted once, when the command finishes: output is buffered and bounded
+    rather than streamed, so hosts receive a single event per command.
+    """
 
     _role: ClassVar[Role] = Role.RUNTIME_EVENT
 
@@ -129,6 +179,10 @@ class TerminalCommandFinished(EventBase):  # type: ignore[misc]
     exit_code: Annotated[int | None, Field(description="Process exit code when available")] = None
     timed_out: Annotated[bool, Field(description="Whether the command timed out")] = False
     error: Annotated[str, Field(description="Failure before an exit code was available")] = ""
+    cancelled: Annotated[
+        bool,
+        Field(description="Whether the command was stopped by cancellation rather than failing"),
+    ] = False
     output_truncated: Annotated[
         bool,
         Field(description="Whether output was omitted from command activity events"),
@@ -178,6 +232,12 @@ class ActivityShellTools(Skill):
     def _resolve_path(self, path: str) -> Path:
         return self._shell._resolve_path(path)
 
+    def _diff_path(self, resolved: Path) -> str:
+        try:
+            return resolved.relative_to(self.cwd).as_posix()
+        except ValueError:
+            return resolved.as_posix().lstrip("/")
+
     def _emit(self, event: EventBase) -> None:
         try:
             self._event_manager.add(event)
@@ -215,10 +275,12 @@ class ActivityShellTools(Skill):
         try:
             result = await self._shell.run(command, stdin=stdin, timeout=timeout)
         except BaseException as error:
+            cancelled = isinstance(error, asyncio.CancelledError)
             self._emit(
                 TerminalCommandFinished(
                     command_id=command_id,
-                    error=str(error) or type(error).__name__,
+                    error="" if cancelled else (str(error) or type(error).__name__),
+                    cancelled=cancelled,
                 )
             )
             raise
@@ -306,10 +368,12 @@ class ActivityShellTools(Skill):
                             truncated=output_truncated,
                         )
                     )
+                cancelled = isinstance(error, asyncio.CancelledError)
                 self._emit(
                     TerminalCommandFinished(
                         command_id=command_id,
-                        error=str(error) or type(error).__name__,
+                        error="" if cancelled else (str(error) or type(error).__name__),
+                        cancelled=cancelled,
                         output_truncated=output_truncated,
                     )
                 )
@@ -320,7 +384,7 @@ class ActivityShellTools(Skill):
     @wraps(ShellTools.read)
     async def read(
         self,
-        path: Annotated[str, spec(description="File path (relative to cwd)")],
+        path: Annotated[str, spec(description="File path (relative to cwd or absolute)")],
         lines: Annotated[
             tuple[int, int] | None,
             spec(description="(start, end) 1-indexed inclusive, or None for whole file"),
@@ -348,7 +412,9 @@ class ActivityShellTools(Skill):
         if not isinstance(path, str):
             return await self._shell.replace(target, old_or_new, new)
 
-        resolved = self._resolve_path(path)
+        resolved = (
+            Path(target.resolved_path) if isinstance(target, Match) else self._resolve_path(path)
+        )
         if isinstance(target, Match):
             old_text = target.text
             start_line = target.start
@@ -375,6 +441,12 @@ class ActivityShellTools(Skill):
         written_text = result.new_text
         bounded_new = pformat(written_text, max_string=_MAX_EVENT_TEXT_CHARS, unquote_strings=True)
         new_truncated = len(written_text) > _MAX_EVENT_TEXT_CHARS
+        diff, diff_complete = _edit_diff(
+            self._diff_path(resolved),
+            old_text,
+            written_text,
+            start_line,
+        )
         self._emit(
             FileEdit(
                 path=str(resolved),
@@ -383,8 +455,9 @@ class ActivityShellTools(Skill):
                 new_text=bounded_new,
                 start_line=start_line,
                 end_line=end_line,
-                diff=_edit_diff(path, bounded_old, bounded_new, start_line),
+                diff=diff,
                 content_complete=not old_truncated and not new_truncated,
+                diff_complete=diff_complete,
             )
         )
         return result
@@ -392,40 +465,67 @@ class ActivityShellTools(Skill):
     @wraps(ShellTools.write_file)
     async def write_file(
         self,
-        path: Annotated[str, spec(description="File path (relative to cwd)")],
+        path: Annotated[str, spec(description="File path (relative to cwd or absolute)")],
         content: Annotated[str, spec(description="Full file content")],
     ) -> FileWrite:
         resolved = self._resolve_path(path)
         existed = resolved.exists()
-        old_text: str | None = None
-        old_complete = True
+        old_diff_text: str | None = None
+        old_content_complete = not existed
         if existed:
             try:
                 with resolved.open("r") as stream:
-                    old_text = stream.read(_MAX_EVENT_TEXT_CHARS + 1)
-                old_complete = len(old_text) <= _MAX_EVENT_TEXT_CHARS
-                old_text = pformat(old_text, max_string=_MAX_EVENT_TEXT_CHARS, unquote_strings=True)
+                    old_diff_text = stream.read(_MAX_DIFF_INPUT_CHARS + 1)
+                old_content_complete = len(old_diff_text) <= _MAX_EVENT_TEXT_CHARS
             except (OSError, UnicodeError):
                 # Observation must not make an otherwise valid overwrite fail.
-                old_complete = False
+                old_content_complete = False
 
         result = await self._shell.write_file(path, content)
+        bounded_old = (
+            pformat(
+                old_diff_text,
+                max_string=_MAX_EVENT_TEXT_CHARS,
+                unquote_strings=True,
+            )
+            if old_diff_text is not None
+            else None
+        )
         bounded_content = pformat(content, max_string=_MAX_EVENT_TEXT_CHARS, unquote_strings=True)
         content_truncated = len(content) > _MAX_EVENT_TEXT_CHARS
+        if existed and old_diff_text is None:
+            diff, diff_complete = _omitted_diff(
+                self._diff_path(resolved),
+                "previous file content could not be read",
+            )
+        else:
+            diff, diff_complete = _edit_diff(
+                self._diff_path(resolved),
+                old_diff_text or "",
+                content,
+                None,
+            )
         self._emit(
             FileEdit(
                 path=str(resolved),
                 operation="update" if existed else "create",
-                old_text=old_text,
+                old_text=bounded_old,
                 new_text=bounded_content,
-                start_line=1 if existed and old_complete and old_text is not None else None,
+                # An existing *empty* file has no original line to point at, so
+                # reporting 1..1 names lines that never existed.
+                start_line=(
+                    1
+                    if existed and old_content_complete and _line_count(old_diff_text or "")
+                    else None
+                ),
                 end_line=(
-                    max(1, _line_count(old_text))
-                    if existed and old_complete and old_text is not None
+                    _line_count(old_diff_text or "")
+                    if existed and old_content_complete and _line_count(old_diff_text or "")
                     else None
                 ),
-                diff=_edit_diff(path, old_text or "", bounded_content, 1),
-                content_complete=old_complete and not content_truncated,
+                diff=diff,
+                content_complete=old_content_complete and not content_truncated,
+                diff_complete=diff_complete,
             )
         )
         return result

nooa_cli-0.0.10/src/nooa_cli/coding/agent.py

@@ -0,0 +1,193 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Host-neutral interactive coding agent used by terminal and ACP hosts."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated, Any
+
+from nooa import Context, hidden, strategy
+from nooa.agentdoc import doc, spec
+from nooa.config import CodeActConfig, PredictConfig
+from nooa.interactive import (
+    InteractiveAgent,
+    RespondReason,
+    RespondResult,
+    SummarizationConfig,
+    install_summarizer,
+)
+from nooa.paths import get_project_dir
+from nooa.skill_registry import SkillRegistry
+from nooa.storage.markers import nosnapshot
+from nooa.strategies import CodeActStrategy, PredictStrategy
+from nooa.tools import SkillWriting, TodoManager
+from nooa.tools.shell_tools import ShellTools
+from nooa_cli.coding.activity import ActivityShellTools
+from nooa_cli.coding.instructions import render_agent_instructions
+from nooa_cli.tools.repo_tools import RepoTools
+
+if TYPE_CHECKING:
+    from nooa.runtime.channels import Channel
+    from nooa.unifiedllm import UnifiedLLM
+
+__all__ = ["CodingAgent", "RespondReason"]
+
+
+class CodingAgent(InteractiveAgent):
+    """A careful software-development agent working in one local repository.
+
+    Inspect repository instructions and relevant code before editing. Preserve
+    unrelated worktree changes. Use the shell for files and commands, the repo
+    tools for definitions and references, and todos for multi-step work.
+
+    Complete and verify the requested work before returning ``DONE``. Send each
+    user-facing answer or question through ``self.message()`` as a complete
+    Markdown document. Return ``NEED_INPUT`` only when human input is required,
+    and ``WAIT`` only while an actual background job is active.
+    """
+
+    # Attributes carrying this agent's own tools. SkillRegistry refuses to let
+    # a later skill — a workspace SKILL.md, a client-forwarded MCP server —
+    # take one over, which would remove the tool while the model is still told
+    # it has it.
+    __protected_skill_attrs__ = frozenset({"shell", "repo", "todo", "libs", "skills"})
+
+    cwd: Annotated[Path, nosnapshot]
+    # Host-driven input channels. These live here rather than on
+    # InteractiveAgent because they are coding-host concepts: slash commands
+    # are a UI affordance whose registry is in this package, and
+    # system_messages carries host continuations such as keep-going.
+    _slash_commands_in: Annotated[Channel, hidden, nosnapshot]
+    slash_commands: Annotated[Any, nosnapshot]
+    _system_messages_in: Annotated[Channel, hidden, nosnapshot]
+    system_messages: Annotated[Any, nosnapshot]
+    shell: Annotated[ActivityShellTools, nosnapshot]
+    repo: Annotated[RepoTools, nosnapshot]
+    todo: TodoManager
+    libs: Annotated[SkillWriting, nosnapshot]
+    skills: Annotated[SkillRegistry, nosnapshot]
+    _base_shell: Annotated[ShellTools, hidden, nosnapshot]
+    _summarizers: Annotated[list[Any], hidden, nosnapshot]
+
+    def __init__(
+        self,
+        llm: UnifiedLLM | None = None,
+        *,
+        cwd: str | Path = ".",
+        summarization: SummarizationConfig | None = None,
+        skills_dirs: list[Path] | None = None,
+        libs_dir: Path | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(llm=llm, **kwargs)
+        self._slash_commands_in = self.queue_manager.queue("slash_commands")
+        self.slash_commands = self._slash_commands_in.reader
+        self._system_messages_in = self.queue_manager.queue("system_messages")
+        self.system_messages = self._system_messages_in.reader
+        self.cwd = Path(cwd).resolve()
+        self._base_shell = ShellTools(cwd=str(self.cwd))
+        self.shell = ActivityShellTools(self._base_shell, self.event_manager)
+        self.repo = RepoTools(root=self.cwd, session=self.shell.session)
+        self.todo = TodoManager()
+        # Libraries live at <project>/.nooa/libs. get_project_dir() resolves
+        # that per process, which is what a one-workspace host like the TUI
+        # wants. A host serving several workspaces at once must say which
+        # project it means, or every session shares one directory — and
+        # SkillWriting puts it on sys.path and activates local.*, so that
+        # would expose one workspace's agent-authored code to another.
+        self.libs = SkillWriting(self, path=libs_dir or get_project_dir("libs"))
+
+        self.skills = SkillRegistry(self)
+        self.skills.register("nemo.shell", self.shell)
+        self.skills.register("nemo.repo", self.repo)
+        self.skills.register("nemo.todo", self.todo)
+        self.skills.register("nemo.libwriting", self.libs)
+        self.skills.activate(["nemo.shell", "nemo.repo", "nemo.todo", "nemo.libwriting"])
+        # Installed ``nooa.skills`` entry points are part of the shared host
+        # surface. Load them so hosts can expose ``@slash_command`` methods,
+        # but leave them inactive until the user opts in with ``/skills``.
+        # Memory is host-configured because its scope, store and owner are
+        # session-specific; loading its default entry point would attach it
+        # even when the host has memory disabled.
+        loaded = set(self.skills.loaded())
+        installed = []
+        for name in self.skills.discovered():
+            attr_name = name.rsplit(".", 1)[-1].replace("-", "_")
+            if name == "nemo.memory" or name in loaded or hasattr(self, attr_name):
+                continue
+            installed.append(name)
+        if installed:
+            self.skills.load(installed)
+        if skills_dirs:
+            self.skills.discover_skills_dirs(skills_dirs)
+
+        self.context["python_tools"] = Context(
+            doc(RepoTools, ActivityShellTools),
+            prefix=True,
+        )
+        self.context["todo_status"] = Context(expr="self.todo.status()")
+        self.context["context_usage"] = Context(
+            expr="self.context_stats.format() if self.context_stats else ''"
+        )
+        instructions = render_agent_instructions(self.cwd)
+        if instructions:
+            self.context["repository_instructions"] = Context(instructions, prefix=True)
+        spec(self, "context", hidden=False)
+        spec(self, "events", hidden=False)
+
+        install_summarizer(summarization or SummarizationConfig(), self)
+
+    def get_summarization_status(self) -> dict[str, Any]:
+        """Return compact history information for host status displays."""
+        tags = self.event_manager.keys()
+        summary_tags = [tag for tag in tags if ".." in tag]
+        summarizers = getattr(self, "_summarizers", [])
+        summarizer = summarizers[0] if summarizers else None
+        stats = self.context_stats
+        return {
+            "active_events": len(tags),
+            "summary_count": len(summary_tags),
+            "summary_tags": summary_tags,
+            "has_summarizer": summarizer is not None,
+            "policy": getattr(summarizer, "policy", "none") if summarizer else "none",
+            "current_tokens": getattr(stats, "total_tokens", 0) if stats else 0,
+            "max_tokens": getattr(summarizer, "max_tokens", 0) if summarizer else 0,
+            "preserve_recent": getattr(summarizer, "preserve_recent", 0) if summarizer else 0,
+        }
+
+    @hidden
+    @strategy(PredictStrategy(PredictConfig(output_serialization="tool_call")))
+    async def name_session(self, user_message: str) -> str:
+        """Generate an ultra-short 2-5 word session title for the conversation
+        opened by the given user message."""
+        ...
+
+    @hidden
+    @strategy(CodeActStrategy(config=CodeActConfig(cell_timeout=1800.0)))
+    async def handle(self, notification: dict[str, list[Any]]) -> RespondResult:
+        """Fulfill the newest coding request delivered in ``notification``.
+
+        Work until the request is complete or genuinely needs user input. Use
+        as many small execution cells as necessary and inspect each result
+        before proceeding. Never claim a check passed without running it.
+
+        End with exactly one ``return_result(RespondReason.<reason>,
+        explanation="...")``. The explanation must say what completed, what
+        input is needed, or which live job is still running.
+        """
+        ...
+
+    @hidden
+    async def close(self) -> None:
+        shell = self.shell
+        try:
+            await self.skills.aclose()
+        finally:
+            try:
+                await self.queue_manager.shutdown()
+            finally:
+                try:
+                    await shell.close()
+                finally:
+                    await self.llm.aclose()

nooa_cli-0.0.10/src/nooa_cli/coding/instructions.py

@@ -0,0 +1,80 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Repository instruction discovery for interactive coding agents."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def discover_agent_instruction_files(working_directory: str | Path) -> tuple[Path, ...]:
+    """Return applicable ``AGENTS.md`` files from repository root to cwd.
+
+    A file in a deeper directory is appended after its parent instruction file,
+    so the resulting context naturally gives the most local instructions the
+    final word. Discovery stops at the nearest Git worktree root. Outside a Git
+    worktree, only the working directory itself is considered.
+    """
+    cwd = Path(working_directory).resolve()
+    root = _git_root(cwd)
+    directories = [cwd]
+    if root is not None:
+        distance = len(cwd.relative_to(root).parts)
+        directories = list(reversed((cwd, *cwd.parents[:distance])))
+
+    return tuple(path for directory in directories if (path := directory / "AGENTS.md").is_file())
+
+
+#: Per-file and combined caps on repository instructions. The content is
+#: workspace-controlled and lands in a prefix context block on every turn, so an
+#: unbounded read is a memory and context-window risk at session setup.
+_MAX_INSTRUCTION_FILE_CHARS = 100_000
+_MAX_INSTRUCTION_TOTAL_CHARS = 200_000
+_SECTION_SEPARATOR = "\n\n---\n\n"
+
+
+def render_agent_instructions(working_directory: str | Path) -> str:
+    """Render applicable repository instructions as one bounded context block.
+
+    Reads are bounded rather than truncated after the fact: the content is
+    workspace-controlled and lands in a prefix context block on every turn, so
+    reading a huge file in full before discarding most of it would still cost
+    the memory. The budget covers the rendered text — headers, separators and
+    truncation markers included — not just the retained file content.
+    """
+    sections: list[str] = []
+    remaining = _MAX_INSTRUCTION_TOTAL_CHARS
+    for path in discover_agent_instruction_files(working_directory):
+        if remaining <= 0:
+            logger.warning("Skipping repository instructions from %s: total limit reached", path)
+            continue
+        budget = min(_MAX_INSTRUCTION_FILE_CHARS, remaining)
+        try:
+            with path.open("r", encoding="utf-8") as stream:
+                # One char past the budget is enough to know it was cut.
+                content = stream.read(budget + 1)
+        except (OSError, UnicodeError):
+            continue
+        truncated = len(content) > budget
+        if truncated:
+            content = content[:budget]
+            logger.warning("Truncating repository instructions from %s at %d chars", path, budget)
+        content = content.strip()
+        if not content:
+            continue
+        if truncated:
+            content += "\n\n[... truncated ...]"
+        section = f"Instructions from {path}:\n\n{content}"
+        remaining -= len(section) + len(_SECTION_SEPARATOR)
+        sections.append(section)
+    return _SECTION_SEPARATOR.join(sections)
+
+
+def _git_root(cwd: Path) -> Path | None:
+    for directory in (cwd, *cwd.parents):
+        if (directory / ".git").exists():
+            return directory
+    return None