python-agent-harness 1.5.0__py3-none-any.whl

python_agent_harness/context_manager.py

@@ -0,0 +1,100 @@
+"""Context management for the agent loop: ratio tracking + compaction.
+
+Extracted from agent.py (no logic changes): the FSM driver delegates
+``_update_context_ratio`` / ``_need_compaction`` / ``compact`` to
+``ContextManager``, which reads/writes the loop's shared state
+(``messages`` / ``session``) through the loop reference.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from . import config
+from .prompts import compact_summary, compacted_messages, user_prompt_texts
+
+
+class ContextManager:
+    """Context-ratio tracking and compaction for one agent loop.
+
+    ``update_context_ratio`` receives the two token-estimator functions
+    from the loop's delegate so the call site keeps resolving them
+    through the ``agent`` module namespace (tests patch
+    ``python_agent_harness.agent.estimate_payload_tokens``).
+    """
+
+    def __init__(self, loop: Any) -> None:
+        self.loop = loop
+
+    def update_context_ratio(
+        self,
+        estimate_payload_tokens: Any,
+        context_window_for: Any,
+    ) -> None:
+        loop = self.loop
+        raw = estimate_payload_tokens(
+            loop.system,
+            [m.to_api() for m in loop.messages],
+            [t.to_api() for t in loop.session.tool_specs()],
+        )
+        loop.session.calibrator.last_raw_estimate = raw
+        calibrated = loop.session.calibrator.calibrate(raw)
+        window = context_window_for(loop.session.model)
+        loop.session.context_ratio = calibrated / float(window)
+        loop.session.notify("context")
+
+    def need_compaction(self) -> bool:
+        loop = self.loop
+        return (
+            loop.top_level
+            and loop.session.tools_enabled
+            and not loop.session.compacting
+            and loop.session.context_ratio is not None
+            and loop.session.context_ratio > config.CONTEXT_TRIGGER
+        )
+
+    def compact(self) -> bool:
+        """Compact the conversation; return True on success.
+
+        On success the history is replaced by the summary frame followed
+        by every real user prompt (nudges and other harness-injected
+        messages excluded), so the model keeps the actual requests; the
+        last prompt is the resume request for the next round.
+        """
+        loop = self.loop
+        prompts = user_prompt_texts(loop.messages)
+        if not prompts:
+            return False
+        loop.session.compacting = True
+        try:
+            conversation = "\n\n".join(f"{m.role}: {m.text()}" for m in loop.messages if m.text())
+            summary = compact_summary(
+                loop.session.client, conversation, cancel_check=loop._is_cancelled
+            )
+            if not summary:
+                return False
+            # The summary replaces the whole conversation history EXCEPT
+            # the system prompt (loop.system is passed separately and
+            # stays untouched): it is part of the user turn, never a
+            # system message.  Every real user prompt (nudges and other
+            # harness-injected messages excluded) is preserved verbatim
+            # after the frame, so the model keeps the actual requests.
+            loop.messages = compacted_messages(summary, prompts)
+            # The shared conversation now is the compacted one: mirror it
+            # onto session.last_messages so the TUI (renders from it) and
+            # a later manual /compact start from the summary, not the old
+            # full history.
+            if loop.top_level and not loop._is_cancelled():
+                loop.session.last_messages = list(loop.messages)
+            # Fresh start for the resumed conversation: the pre-compaction
+            # nudge budget must not carry over, or the first terminal
+            # answer after compaction ends the run immediately.
+            loop.supervisor.reset_nudges()
+            loop.session.notify("compact")
+            return True
+        except Exception as e:  # noqa: BLE001 - compaction failure is non-fatal
+            loop.session.notify("error")
+            loop.session.log(f"compaction failed: {e}")
+            return False
+        finally:
+            loop.session.compacting = False

python_agent_harness/diffrender.py

@@ -0,0 +1,84 @@
+"""Unified-diff generation and rich rendering for file-changing tools.
+
+``unified_diff`` builds a standard unified diff between two file
+contents (used by Edit/Write to record what actually changed).
+``render_diff`` turns that text into a red/green ``rich`` renderable
+suitable for the TUI's tool-output panel.
+"""
+
+from __future__ import annotations
+
+import difflib
+
+from rich.console import Group
+from rich.text import Text
+
+MAX_DIFF_LINES = 400  # truncation cap for the rendered (not stored) diff
+
+
+def unified_diff(
+    old_content: str,
+    new_content: str,
+    path: str,
+    context_lines: int = 3,
+) -> str:
+    """Return a unified diff string between OLD_CONTENT and NEW_CONTENT.
+
+    Empty string when the two are identical (nothing to show).
+    Lines at EOF without a trailing newline get a git-style
+    ``\`` marker so the diff round-trips
+    (the Edit tool's diff mode parses markers and applies them).
+    """
+    if old_content == new_content:
+        return ""
+    old_lines = old_content.splitlines(keepends=True)
+    new_lines = new_content.splitlines(keepends=True)
+    diff = difflib.unified_diff(
+        old_lines,
+        new_lines,
+        fromfile=f"a/{path}",
+        tofile=f"b/{path}",
+        n=context_lines,
+        lineterm="\n",
+    )
+    out: list[str] = []
+    for line in diff:
+        out.append(line)
+        if line[:1] in ("-", "+", " ") and not line.endswith("\n"):
+            # a content line at EOF without a trailing newline: difflib
+            # emits it bare, which would corrupt the joined text; mark
+            # it like git does so the diff round-trips (the Edit tool's
+            # diff mode parses markers and applies them)
+            out.append("\n\\n")
+    return "".join(out)
+
+
+def render_diff(diff_text: str, max_lines: int = MAX_DIFF_LINES) -> Group:
+    """Render a unified diff as a rich renderable (red '-' / green '+').
+
+    Hunk headers (@@ ...@@) and file headers (---/+++) are dimmed;
+    added lines are green, removed lines are red, context lines are
+    plain.  Long diffs are truncated with a marker line.
+    """
+    lines = diff_text.splitlines()
+    truncated = len(lines) > max_lines
+    if truncated:
+        lines = lines[:max_lines]
+
+    rows: list[Text] = []
+    for line in lines:
+        if line.startswith("+++") or line.startswith("---"):
+            rows.append(Text(line, style="dim bold"))
+        elif line.startswith("@@"):
+            rows.append(Text(line, style="cyan"))
+        elif line.startswith("+"):
+            rows.append(Text(line, style="green"))
+        elif line.startswith("-"):
+            rows.append(Text(line, style="red"))
+        else:
+            rows.append(Text(line, style="dim"))
+    if truncated:
+        rows.append(Text("… [diff truncated]", style="dim italic"))
+    if not rows:
+        rows.append(Text("(no changes)", style="dim italic"))
+    return Group(*rows)

python_agent_harness/mcp/__init__.py

@@ -0,0 +1,21 @@
+"""MCP (Model Context Protocol) client support.
+
+Optional: requires the ``mcp`` extra (``pip install -e ".[mcp]"``).
+Importing this package never requires the SDK — only actually
+connecting to an MCP server does.
+"""
+
+from __future__ import annotations
+
+from .client import MCPClient, MCPUnavailableError
+from .config import MCPConfig, MCPServerConfig
+from .manager import MCPManager, MCPToolSpec
+
+__all__ = [
+    "MCPClient",
+    "MCPConfig",
+    "MCPManager",
+    "MCPServerConfig",
+    "MCPToolSpec",
+    "MCPUnavailableError",
+]

python_agent_harness/mcp/client.py

@@ -0,0 +1,161 @@
+"""Thin wrapper around the official MCP Python SDK (client side).
+
+This module is the ONLY place that touches the SDK.  The rest of the
+harness sees plain dicts and strings, so a future SDK API change (the
+v1 → v2 line already renamed FastMCP → MCPServer and moved the client
+onto ``mcp.Client``) stays contained here.
+
+The SDK is optional: importing this module never fails without it.  The
+``mcp`` extra (``pip install -e ".[mcp]"``) provides ``mcp>=2.0,<3``;
+without it every operation raises :class:`MCPUnavailableError`.
+
+The wrapper is async (the SDK is async); :class:`MCPManager` drives it
+from the harness's synchronous world through a dedicated event-loop
+thread.  SDK types never leak out: ``list_tools`` returns plain dicts
+and ``call_tool`` returns a plain dict with keys ``content`` (list of
+content-block dicts), ``structured_content`` and ``is_error``.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+try:
+    from mcp import Client
+    from mcp.client.sse import sse_client
+    from mcp.client.stdio import StdioServerParameters, stdio_client
+    from mcp.client.streamable_http import streamable_http_client
+
+    _MCP_AVAILABLE = True
+except ImportError:  # pragma: no cover - depends on the optional extra
+    _MCP_AVAILABLE = False
+
+
+class MCPUnavailableError(RuntimeError):
+    """Raised when MCP is configured but the optional SDK is not installed.
+
+    Fix: ``pip install -e ".[mcp]"``.
+    """
+
+
+def _require_sdk() -> None:
+    if not _MCP_AVAILABLE:
+        raise MCPUnavailableError(
+            "MCP support requires the optional `mcp` extra — install with `pip install -e '.[mcp]'`"
+        )
+
+
+class MCPClient:
+    """One connection to one MCP server; hides the official SDK.
+
+    Use as an async context manager::
+
+        async with MCPClient(config) as client:
+            tools = await client.list_tools()
+            result = await client.call_tool("search", {"q": "x"})
+
+    All SDK exceptions propagate as-is (connection refused, protocol
+    errors, ...); the manager/tool layer turns them into normal tool
+    error strings.
+    """
+
+    def __init__(self, config: Any) -> None:
+        from .config import MCPServerConfig
+
+        self.config: MCPServerConfig = config
+        self._client: Any = None
+        self._http_client: Any = None
+
+    async def __aenter__(self) -> MCPClient:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    def _transport(self) -> Any:
+        """Build the SDK transport for this server's config."""
+        cfg = self.config
+        if cfg.transport not in ("stdio", "streamable-http", "sse"):
+            raise ValueError(
+                f"MCP server {cfg.name or '(unnamed)'!r}: unknown transport {cfg.transport!r}"
+            )
+        if cfg.transport == "stdio":
+            # command is validated non-None by MCPServerConfig.validate
+            assert cfg.command is not None
+            env = None
+            if cfg.env:
+                env = {name: os.environ[name] for name in cfg.env if name in os.environ}
+            return stdio_client(StdioServerParameters(command=cfg.command, args=cfg.args, env=env))
+        # url is validated non-None by MCPServerConfig.validate for the
+        # HTTP transports
+        assert cfg.url is not None
+        if cfg.transport == "streamable-http":
+            if cfg.headers:
+                import httpx2  # shipped as part of the mcp SDK
+
+                self._http_client = httpx2.AsyncClient(headers=cfg.headers)
+                return streamable_http_client(cfg.url, http_client=self._http_client)
+            return streamable_http_client(cfg.url)
+        if cfg.transport == "sse":
+            return sse_client(cfg.url, headers=cfg.headers or None)
+        # unreachable: the transport whitelist at the top rejects
+        # everything else
+        raise ValueError(
+            f"MCP server {cfg.name!r}: unknown transport {cfg.transport!r}"
+        )  # pragma: no cover
+
+    async def connect(self) -> None:
+        """Establish the connection (spawn process / open HTTP session)."""
+        _require_sdk()
+        self._client = Client(
+            server=self._transport(),
+            read_timeout_seconds=self.config.timeout,
+        )
+        await self._client.__aenter__()
+
+    async def close(self) -> None:
+        """Tear down the connection (best effort, never raises)."""
+        import contextlib
+
+        client, self._client = self._client, None
+        if client is not None:
+            with contextlib.suppress(Exception):  # teardown noise is not an error
+                await client.__aexit__(None, None, None)
+        http_client, self._http_client = self._http_client, None
+        if http_client is not None:
+            with contextlib.suppress(Exception):  # teardown noise is not an error
+                await http_client.aclose()
+
+    async def list_tools(self) -> list[dict[str, Any]]:
+        """tools/list — the server's tool descriptors as plain dicts."""
+        _require_sdk()
+        result = await self._client.list_tools()
+        return [
+            {
+                "name": t.name,
+                "description": t.description or "",
+                "input_schema": t.input_schema if isinstance(t.input_schema, dict) else {},
+            }
+            for t in result.tools
+        ]
+
+    async def call_tool(self, name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+        """tools/call — returns a plain dict (content blocks, structured
+        content, is_error).  Server-reported failures surface as
+        ``is_error=True``, NOT as exceptions."""
+        _require_sdk()
+        result = await self._client.call_tool(name, arguments or {})
+        return {
+            "content": [_content_block_to_dict(b) for b in result.content],
+            "structured_content": result.structured_content,
+            "is_error": bool(result.is_error),
+        }
+
+
+def _content_block_to_dict(block: Any) -> dict[str, Any]:
+    """One MCP content block → plain dict (text/image/audio/resource/...)."""
+    if hasattr(block, "model_dump"):
+        return block.model_dump(exclude_none=True)
+    return {"type": "unknown", "raw": str(block)}

python_agent_harness/mcp/config.py

@@ -0,0 +1,130 @@
+"""MCP server configuration for python-agent-harness.
+
+MCP support is OPTIONAL: install the harness with ``pip install -e ".[mcp]"``
+to get the official ``mcp`` SDK (the ``mcp`` extra).  This module only
+defines plain configuration data classes — importing it never imports the
+SDK, so the base harness stays dependency-free.
+
+Transports (per the MCP spec):
+
+- ``stdio``: spawn ``command`` with ``args`` as a subprocess; ``env``
+  lists environment variable names passed through from the harness
+  process (e.g. ``["GITHUB_TOKEN"]``).
+- ``streamable-http``: connect to ``url``; ``headers`` (e.g.
+  Authorization) are sent with every request.  The direction to target
+  for new remote deployments.
+- ``sse``: connect to ``url`` over the legacy SSE transport.
+
+Concurrency policy: ``parallel`` marks the server's tools as safe for
+concurrent execution (read-only servers); the tool then runs in the
+background like Bash/Agent.  The default is conservative serial
+execution.  The harness — not the MCP protocol — retains authority
+over this.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+TRANSPORTS = ("stdio", "streamable-http", "sse")
+
+
+@dataclass
+class MCPServerConfig:
+    """Configuration for one MCP server connection.
+
+    ``name`` is optional: when the server lives in an ``MCPConfig``
+    dict the dict key is authoritative (it fills ``name`` on
+    construction), so the design's compact form works::
+
+        MCPConfig(servers={"github": MCPServerConfig(command="npx", ...)})
+
+    ``enabled=False`` keeps the server in the config file without
+    connecting it (a documented example, or a temporarily-disabled
+    server).
+    """
+
+    name: str = ""
+    transport: str = "stdio"
+    command: str | None = None
+    args: list[str] = field(default_factory=list)
+    env: list[str] = field(default_factory=list)
+    url: str | None = None
+    headers: dict[str, str] = field(default_factory=dict)
+    parallel: bool = False
+    timeout: float | None = None
+    enabled: bool = True
+
+    def validate(self) -> None:
+        label = self.name or "(unnamed)"
+        if self.transport not in TRANSPORTS:
+            raise ValueError(
+                f"MCP server {label!r}: unknown transport {self.transport!r} "
+                f"(expected one of {', '.join(TRANSPORTS)})"
+            )
+        if self.transport == "stdio":
+            if not self.command:
+                raise ValueError(f"MCP server {label!r}: stdio transport requires `command`")
+        elif not self.url:
+            raise ValueError(f"MCP server {label!r}: {self.transport} transport requires `url`")
+
+
+@dataclass
+class MCPConfig:
+    """The set of MCP servers for one session.
+
+    Usage (the compact form — the dict key IS the server name)::
+
+        config = MCPConfig(
+            servers={
+                "github": MCPServerConfig(
+                    transport="stdio",
+                    command="npx",
+                    args=["-y", "@modelcontextprotocol/server-github"],
+                    env=["GITHUB_TOKEN"],
+                ),
+                "remote": MCPServerConfig(
+                    transport="streamable-http",
+                    url="http://localhost:8000/mcp",
+                ),
+            }
+        )
+    """
+
+    servers: dict[str, MCPServerConfig] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        # The dict key is the authoritative server name: fill in any
+        # config whose name was left unset (compact construction).
+        for key, server in self.servers.items():
+            if not server.name:
+                server.name = key
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any] | None) -> MCPConfig:
+        """Build from a plain mapping (e.g. the config file's ``mcp.servers``).
+
+        Raises ValueError on malformed entries (unknown transport, missing
+        command/url) so config errors surface at session start, not mid-run.
+        """
+        config = cls()
+        for name, raw in (data or {}).items():
+            if not isinstance(raw, dict):
+                raise ValueError(f"MCP server {name!r}: expected an object")
+            server = MCPServerConfig(
+                name=name,
+                transport=str(raw.get("transport", "stdio")),
+                command=raw.get("command"),
+                args=[str(a) for a in (raw.get("args") or [])],
+                env=[str(e) for e in (raw.get("env") or [])],
+                url=raw.get("url"),
+                headers={str(k): str(v) for k, v in (raw.get("headers") or {}).items()},
+                parallel=bool(raw.get("parallel", False)),
+                timeout=raw.get("timeout"),
+                enabled=bool(raw.get("enabled", True)),
+            )
+            server.validate()
+            config.servers[name] = server
+        return config