novacode-cli 1.2.0__py3-none-any.whl

novacode_cli/agents/async_agents/_mcp_tools.py

@@ -0,0 +1,192 @@
+"""MCP tools for a background (async) agent graph.
+
+A background graph is built by :func:`build_specialist_graph`, which resolves the
+agent's declared tool names against ``novacode_cli.tools``. MCP tools are not in
+that module — they are discovered at runtime from ``~/.nova/mcp.json`` — so every
+``serena_*`` / ``playwright_*`` / ``cua-driver_*`` name an agent declares used to
+be dropped without a word. An agent whose prompt is written around symbol
+navigation then ran in the background with no symbol tool at all.
+
+The server process can fix this itself: it is a subprocess of the same
+interpreter with the same environment (``server_launcher.build_env``), and the
+MCP config is a plain file, so there is no IPC and nothing to pass between
+processes. This module is the one place that turns "the names in an agent's
+frontmatter" into real MCP tools, reusing the same discovery the in-process path
+uses (``MCPMiddleware``) and the same server-prefix convention the in-process
+grant uses (``core_agent._grant_mcp_tools``).
+
+**Failure is never fatal here.** ``langgraph`` loads every graph in the config at
+startup and refuses to start if one fails to load, so an MCP server that is
+missing, slow or broken must degrade to "this agent has fewer tools" rather than
+"no background agent can run". Every path in :func:`mcp_tools_for` returns a
+list, and the empty list is a normal answer.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from langchain_core.tools import BaseTool
+
+logger = logging.getLogger(__name__)
+
+#: Discovery results, keyed by the sorted tuple of requested tool names.
+#:
+#: The server imports every registered graph at startup, and each graph would
+#: otherwise run its own discovery — spawning the same MCP servers once per
+#: agent. Cold-starting a stdio server (``npx``/``uvx``) is seconds, so that
+#: multiplies badly. Keyed by the request rather than by server so two agents
+#: asking for different subsets each get exactly their own tools.
+_CACHE: dict[tuple[str, ...], list[BaseTool]] = {}
+
+#: How long discovery may take before the agent is built without MCP tools.
+#:
+#: Generous, because a cold stdio server (``npx``/``uvx``) may download a package
+#: on first run, and the same 90 s the in-process path allows is the right order
+#: of magnitude. It is a ceiling on a *background* thread, so a slow server costs
+#: this agent its MCP tools rather than the server its startup.
+_DISCOVERY_TIMEOUT = 90.0
+
+
+def mcp_tools_for(names: list[str] | tuple[str, ...]) -> list[BaseTool]:
+    """The MCP tools among *names*, discovered from the user's MCP config.
+
+    Args:
+        names: Tool names as written in an ``agent.md``'s ``tools:`` frontmatter,
+            e.g. ``["serena_find_symbol", "code_search"]``. Names that are not MCP
+            tools are ignored here — the caller resolves those against
+            ``novacode_cli.tools``.
+
+    Returns:
+        The discovered MCP tools whose names appear in *names*, in discovery
+        order. Empty when there is no MCP config, no server could be reached, or
+        none of *names* is an MCP tool. Never raises: a background agent with
+        fewer tools is strictly better than a server that will not boot.
+    """
+    wanted = tuple(sorted({n for n in names if n}))
+    if not wanted:
+        return []
+    if wanted in _CACHE:
+        return _CACHE[wanted]
+
+    tools, ok = _discover(wanted)
+    # Only a *successful* discovery is cached. A failure is usually transient — a
+    # server that was slow to start, or a timeout — and caching it would deny the
+    # agent its tools for the life of the process, with no way back short of a
+    # restart. A retry costs one more spawn; a permanent empty answer costs the
+    # agent the tools its prompt is written around.
+    if ok:
+        _CACHE[wanted] = tools
+    return tools
+
+
+def _discover(wanted: tuple[str, ...]) -> tuple[list[BaseTool], bool]:
+    """Run MCP discovery and keep the tools named in *wanted*.
+
+    Returns the tools and whether discovery itself succeeded, so the caller can
+    tell "this agent has no MCP tools" from "discovery did not work this time"
+    and cache only the former.
+
+    Split out so :func:`mcp_tools_for` stays a cache lookup plus one call, and so
+    the whole discovery can be wrapped in a single guard.
+    """
+    try:
+        from novacode_cli.mcp import get_shared_mcp_middleware
+
+        middleware = get_shared_mcp_middleware()
+        available = list(_discover_off_loop(middleware))
+    except Exception:  # noqa: BLE001 — no MCP tools is a valid outcome
+        logger.warning(
+            "could not discover MCP tools for a background agent; it will run without them",
+            exc_info=True,
+        )
+        return [], False
+
+    wanted_set = set(wanted)
+    kept = [t for t in available if _tool_name(t) in wanted_set]
+    if not kept and wanted:
+        # Worth a line: the agent asked for tools that exist in no configured
+        # server, which is usually a typo or a server the user has not added.
+        logger.info(
+            "none of the %d requested MCP tool(s) were found in the MCP config: %s",
+            len(wanted),
+            ", ".join(wanted),
+        )
+    # "Discovery worked" is not the same as "no server answered". With servers
+    # configured but not one tool discovered, the servers are down or still
+    # starting, and caching that would turn a transient outage into a permanent
+    # "this agent has no MCP tools". Only a discovery that actually produced
+    # something, or a config with nothing to discover, is worth caching.
+    return kept, bool(available) or not _configured_servers()
+
+
+def _configured_servers() -> bool:
+    """Whether the user has any MCP server configured at all.
+
+    Used to tell "there is nothing to discover, so an empty result is the real
+    answer" from "servers are configured but none answered, so the empty result
+    is an outage". Never raises: an unreadable config is treated as "none", which
+    makes the caller cache the empty result rather than retry forever.
+    """
+    try:
+        from novacode_cli.mcp import get_shared_mcp_middleware
+
+        return bool(get_shared_mcp_middleware().mcp_config.list_servers())
+    except Exception:  # noqa: BLE001 — an unreadable config is not an outage
+        return False
+
+
+def _discover_off_loop(middleware: object) -> list[BaseTool]:
+    """Discover MCP tools without blocking the caller's event loop.
+
+    ``langgraph dev`` installs ``blockbuster``, which turns a blocking call on the
+    event loop into an exception. Spawning a stdio MCP server does exactly that:
+    the ``mcp`` library resolves the command with ``shutil.which``, which calls
+    ``os.access``. So discovery is run in a worker thread with its own loop, the
+    same way the in-process path does it (``MCPMiddleware._discover_tools_sync``
+    already uses a ``ThreadPoolExecutor`` for this reason).
+
+    A graph is imported on the server's loop, so calling the sync entry point
+    directly here would trip blockbuster and take the whole server down with it.
+
+    The pool is shut down with ``wait=False`` on timeout, deliberately. A
+    ``with`` block would call ``shutdown(wait=True)`` and block until the worker
+    finished, so a hung MCP server would still stall the server's startup and
+    ``_DISCOVERY_TIMEOUT`` would bound nothing. A thread left running is the
+    lesser evil: it is one per distinct request, and the process is a dev server.
+    """
+    import asyncio
+    import concurrent.futures
+
+    def _run() -> list[BaseTool]:
+        # A fresh loop in this thread: the caller's loop is not ours to touch.
+        asyncio.run(middleware._discover_tools_async())  # type: ignore[attr-defined]
+        return list(middleware.tools)  # type: ignore[attr-defined]
+
+    pool = concurrent.futures.ThreadPoolExecutor(max_workers=1)
+    try:
+        return pool.submit(_run).result(timeout=_DISCOVERY_TIMEOUT)
+    finally:
+        # wait=False: never block the caller on a worker that overran the budget.
+        pool.shutdown(wait=False)
+
+
+def _tool_name(tool: object) -> str:
+    """A tool's name, or ``""`` when it has none.
+
+    Mirrors ``core_agent._tool_name``: the name is what the prefix match and the
+    caller's request are both expressed in, so a tool without one is simply not
+    a match rather than an error.
+    """
+    return str(getattr(tool, "name", "") or "")
+
+
+def reset_cache() -> None:
+    """Drop the discovery cache.
+
+    For tests, and for a caller that has just changed the MCP config and wants
+    the next graph build to see it.
+    """
+    _CACHE.clear()

novacode_cli/agents/async_agents/_specialist.py

@@ -0,0 +1,84 @@
+"""Build a background graph from a prompt and a list of tool names.
+
+Shared by the async agents that are just that: a prompt, Nova tools named by
+string, and file access to the session's workspace. An agent that already exists
+in-process (``default_subagents/prompt.py``) can be handed over as it is, so the
+two forms never drift apart.
+
+A declared name is resolved against two sources, because the in-process subagent
+path does the same: ``novacode_cli.tools`` for Nova's own tools, and the user's
+MCP config for ``serena_*`` / ``playwright_*`` / ``cua-driver_*`` (see
+``_mcp_tools``). Only the first was consulted here, so an agent whose prompt is
+written around symbol navigation ran in the background with no symbol tool.
+
+Only work that is long and self-contained belongs here; an agent that edits code
+interactively needs the approvals that do not reach this server.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import deepagents
+from novacode_cli.context.snapshot import background_context_middleware
+from deepagents.backends.filesystem import FilesystemBackend
+
+from novacode_cli.agents.async_context import AsyncModelOverrideMiddleware, NovaAsyncContext
+from novacode_cli.agents.async_workspace import workspace_root
+from novacode_cli.config.model_create import build_async_agent_model
+
+BACKGROUND_NOTE = """
+
+## You are running in the background
+
+Nobody is watching this run and nobody can answer a question, so never ask one:
+make the reasonable assumption, state it, and carry on. Your final message is the
+whole deliverable. Whoever dispatched you sees only that, so make it a complete,
+self-contained report rather than a note that work was done.
+"""
+
+
+def build_specialist_graph(
+    name: str,
+    definition: dict[str, Any],
+    *,
+    extra_tools: list[Any] | None = None,
+    note: str = "",
+) -> Any:
+    """A background graph for the agent described by *definition*.
+
+    Args:
+        name: The graph's agent name (its id in ``langgraph.json``).
+        definition: A ``{"prompt", "tools"}`` entry.
+        extra_tools: Tools this background form needs beyond the named ones.
+        note: Anything the background form does differently from the prompt.
+    """
+    import novacode_cli.tools as nova_tools
+    from novacode_cli.agents.async_agents import _tools as background_tools
+    from novacode_cli.agents.async_agents._mcp_tools import mcp_tools_for
+    from novacode_cli.security.delegated_approval import DelegatedApprovalMiddleware
+    from novacode_cli.skills.libraries import background_library
+
+    declared = definition.get("tools", [])
+    # File tools (ls / read_file / glob / grep / write_file) come from the
+    # backend, so only the names that are real Nova tools are looked up: the
+    # session's own, then the background-only ones (git, linters, run_tests).
+    named = [
+        getattr(source, n)
+        for n in declared
+        if (source := next((m for m in (nova_tools, background_tools) if hasattr(m, n)), None))
+    ]
+    # MCP tools are not in novacode_cli.tools — they are discovered from the
+    # user's MCP config — so they are resolved separately. Best-effort: an
+    # unreachable MCP server yields fewer tools, never a graph that fails to
+    # build (which would stop the whole server from starting).
+    mcp = mcp_tools_for(declared)
+    return deepagents.create_deep_agent(
+        name=name,
+        model=build_async_agent_model(),
+        tools=[*named, *mcp, *(extra_tools or [])],
+        system_prompt=definition["prompt"] + BACKGROUND_NOTE + note,
+        backend=FilesystemBackend(root_dir=str(workspace_root()), virtual_mode=True),
+        middleware=[AsyncModelOverrideMiddleware(), DelegatedApprovalMiddleware(), background_library(name, definition), *background_context_middleware()],
+        context_schema=NovaAsyncContext,
+    )

novacode_cli/agents/async_agents/_test_commands.py

@@ -0,0 +1,89 @@
+"""The background test runner's one tool: test-runner commands only, no shell.
+
+Kept apart from ``test_runner.py`` because that module builds a graph (and a
+model) on import, and this is the part that has to be testable on its own.
+"""
+
+from __future__ import annotations
+
+import shlex
+import subprocess
+
+from langchain_core.tools import tool
+
+from novacode_cli.agents.async_workspace import workspace_root
+
+#: What a command may start with. This runs unattended, so it is a list of test
+#: runners rather than a shell: nothing here can be told to delete or push.
+ALLOWED_PREFIXES: tuple[tuple[str, ...], ...] = (
+    ("pytest",),
+    ("python", "-m", "pytest"),
+    ("python", "-m", "unittest"),
+    ("uv", "run", "pytest"),
+    ("uv", "run", "python", "-m", "pytest"),
+    ("npm", "test"),
+    ("npm", "run", "test"),
+    ("pnpm", "test"),
+    ("yarn", "test"),
+    ("npx", "vitest"),
+    ("npx", "jest"),
+    ("go", "test"),
+    ("cargo", "test"),
+    ("dotnet", "test"),
+    ("mvn", "test"),
+    ("gradle", "test"),
+    ("make", "test"),
+)
+_SHELL_CHARS = set("|&;<>`$\n\r")
+_TAIL_CHARS = 12_000
+
+
+def parse_test_command(command: str) -> list[str] | str:
+    """The argv for *command*, or a message saying why it will not be run."""
+    if _SHELL_CHARS & set(command):
+        return "Refused: pipes, redirects and chained commands are not allowed. Give one test command."
+    try:
+        argv = shlex.split(command, posix=True)
+    except ValueError as exc:
+        return f"Refused: could not parse the command ({exc})."
+    head = [a.lower().removesuffix(".exe") for a in argv]
+    if head and head[0] in ("python3", "py"):
+        head[0] = "python"
+    if not any(tuple(head[: len(p)]) == p for p in ALLOWED_PREFIXES):
+        allowed = ", ".join(" ".join(p) for p in ALLOWED_PREFIXES)
+        return f"Refused: only test runners can be run here. Start the command with one of: {allowed}."
+    return argv
+
+
+@tool
+def run_tests(command: str, timeout_seconds: int = 900) -> str:
+    """Run a test command in the project and return its exit code and output.
+
+    Args:
+        command: One test-runner command, e.g. ``pytest tests/ -x -q`` or ``npm test``.
+            No pipes, redirects or chaining.
+        timeout_seconds: Give up after this long (default 15 minutes, at most 60).
+
+    Returns:
+        The exit code and the end of the combined output.
+    """
+    argv = parse_test_command(command)
+    if isinstance(argv, str):
+        return argv
+    try:
+        result = subprocess.run(  # noqa: S603 — argv is allowlisted above, no shell
+            argv,
+            capture_output=True,
+            text=True,
+            errors="replace",
+            cwd=workspace_root(),
+            timeout=max(10, min(int(timeout_seconds), 3600)),
+        )
+    except FileNotFoundError:
+        return f"Could not run `{argv[0]}`: it is not installed or not on PATH."
+    except subprocess.TimeoutExpired:
+        return f"Timed out after {timeout_seconds}s. Run a smaller selection of tests."
+    output = (result.stdout or "") + (result.stderr or "")
+    if len(output) > _TAIL_CHARS:
+        output = "… (earlier output omitted)\n" + output[-_TAIL_CHARS:]
+    return f"exit code {result.returncode}\n{output}"