sid-harness 0.3.0__py3-none-any.whl

sid_harness/tools/mcp_client.py

@@ -0,0 +1,285 @@
+"""Minimal MCP (Model Context Protocol) client over stdio and HTTP (SUB-56).
+
+JSON-RPC 2.0. The stdio transport uses the spec's newline-delimited framing
+(one JSON-RPC message per line); the HTTP transport POSTs a single JSON-RPC
+message and reads the JSON response. Standard library only.
+
+This is a client, not an engine: the tools it exposes are registered into the
+SID ``ToolRegistry`` (``registry.py``) and settle through the same loop.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import urllib.error
+import urllib.request
+from typing import Any
+
+DEFAULT_PROTOCOL_VERSION = "2024-11-05"
+
+
+class MCPError(RuntimeError):
+    """An MCP call could not be completed (transport, protocol, or server error)."""
+
+
+class StdioTransport:
+    """Newline-delimited JSON-RPC over a child process's stdin/stdout."""
+
+    def __init__(
+        self,
+        command: str,
+        args: list[str] | None = None,
+        *,
+        cwd: str | None = None,
+        env: dict[str, str] | None = None,
+    ) -> None:
+        try:
+            self._proc = subprocess.Popen(
+                [command, *(args or [])],
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                encoding="utf-8",
+                bufsize=1,
+                cwd=cwd,
+                env=env,
+            )
+        except OSError as exc:
+            raise MCPError(f"could not start MCP stdio server {command!r}: {exc}") from exc
+
+    def request(self, message: dict[str, Any]) -> dict[str, Any]:
+        self._write(message)
+        assert self._proc.stdout is not None
+        while True:
+            line = self._proc.stdout.readline()
+            if not line:
+                raise MCPError("MCP stdio server closed the stream before replying")
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                payload = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(payload, dict) and payload.get("id") == message.get("id"):
+                return payload
+
+    def notify(self, message: dict[str, Any]) -> None:
+        self._write(message)
+
+    def _write(self, message: dict[str, Any]) -> None:
+        if self._proc.stdin is None:
+            raise MCPError("MCP stdio server stdin is unavailable")
+        self._proc.stdin.write(json.dumps(message) + "\n")
+        self._proc.stdin.flush()
+
+    def close(self) -> None:
+        if self._proc.stdin is not None:
+            try:
+                self._proc.stdin.close()
+            except OSError:
+                pass
+        try:
+            self._proc.terminate()
+            self._proc.wait(timeout=5)
+        except Exception:  # pragma: no cover - best-effort teardown
+            try:
+                self._proc.kill()
+            except Exception:
+                pass
+
+
+class HTTPTransport:
+    """JSON-RPC over HTTP POST (one request, one JSON response)."""
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self.url = url
+        self.headers = {"Content-Type": "application/json", **(headers or {})}
+        self.timeout = timeout
+
+    def request(self, message: dict[str, Any]) -> dict[str, Any]:
+        data = json.dumps(message).encode("utf-8")
+        req = urllib.request.Request(
+            self.url, data=data, headers=self.headers, method="POST"
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as response:
+                body = response.read().decode("utf-8")
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode("utf-8", "replace")
+            raise MCPError(f"MCP HTTP {exc.code}: {detail[:300]}") from exc
+        except urllib.error.URLError as exc:
+            raise MCPError(f"MCP endpoint unreachable at {self.url}: {exc.reason}") from exc
+        try:
+            parsed = json.loads(body)
+        except json.JSONDecodeError as exc:
+            raise MCPError("MCP endpoint returned a non-JSON response") from exc
+        if not isinstance(parsed, dict):
+            raise MCPError("MCP endpoint returned an unexpected response shape")
+        return parsed
+
+    def notify(self, message: dict[str, Any]) -> None:
+        data = json.dumps(message).encode("utf-8")
+        req = urllib.request.Request(
+            self.url, data=data, headers=self.headers, method="POST"
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout):
+                pass
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode("utf-8", "replace")
+            raise MCPError(f"MCP HTTP {exc.code}: {detail[:300]}") from exc
+        except urllib.error.URLError as exc:
+            raise MCPError(f"MCP endpoint unreachable at {self.url}: {exc.reason}") from exc
+
+    def close(self) -> None:  # nothing persistent to release
+        return None
+
+
+class MCPClient:
+    """A small MCP client: initialize, list tools, call a tool."""
+
+    def __init__(
+        self,
+        transport: Any,
+        *,
+        client_name: str = "sid-harness",
+        client_version: str = "0.1.0",
+        protocol_version: str = DEFAULT_PROTOCOL_VERSION,
+    ) -> None:
+        self._transport = transport
+        self._client_name = client_name
+        self._client_version = client_version
+        self._protocol_version = protocol_version
+        self._request_id = 0
+        self.initialized = False
+
+    def _next_id(self) -> int:
+        self._request_id += 1
+        return self._request_id
+
+    def _request(self, method: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        message: dict[str, Any] = {
+            "jsonrpc": "2.0",
+            "id": self._next_id(),
+            "method": method,
+        }
+        if params is not None:
+            message["params"] = params
+        response = self._transport.request(message)
+        error = response.get("error")
+        if error:
+            raise MCPError(f"MCP {method} failed: {error}")
+        result = response.get("result")
+        return result if isinstance(result, dict) else {}
+
+    def _notify(self, method: str, params: dict[str, Any] | None = None) -> None:
+        message: dict[str, Any] = {"jsonrpc": "2.0", "method": method}
+        if params is not None:
+            message["params"] = params
+        self._transport.notify(message)
+
+    def initialize(self) -> dict[str, Any]:
+        result = self._request(
+            "initialize",
+            {
+                "protocolVersion": self._protocol_version,
+                "capabilities": {},
+                "clientInfo": {"name": self._client_name, "version": self._client_version},
+            },
+        )
+        self._notify("notifications/initialized")
+        self.initialized = True
+        return result
+
+    def list_tools(self) -> list[dict[str, Any]]:
+        result = self._request("tools/list", {})
+        tools = result.get("tools")
+        if not isinstance(tools, list):
+            raise MCPError("MCP tools/list returned an unexpected shape")
+        return tools
+
+    def call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> dict[str, Any]:
+        return self._request("tools/call", {"name": name, "arguments": arguments or {}})
+
+    def close(self) -> None:
+        self._transport.close()
+
+
+def _tool_schema(tool: dict[str, Any], *, exposed_name: str) -> dict[str, Any]:
+    return {
+        "type": "function",
+        "function": {
+            "name": exposed_name,
+            "description": tool.get("description") or f"MCP tool {exposed_name}",
+            "parameters": tool.get("inputSchema")
+            or {"type": "object", "properties": {}, "additionalProperties": False},
+        },
+    }
+
+
+def mcp_tool_schemas(
+    tools: list[dict[str, Any]], *, prefix: str | None = None
+) -> list[dict[str, Any]]:
+    """Convert MCP tool descriptors to the loop's function-schema shape."""
+    schemas: list[dict[str, Any]] = []
+    for tool in tools:
+        name = str(tool.get("name") or "").strip()
+        if not name:
+            continue
+        exposed = f"{prefix}_{name}" if prefix else name
+        schemas.append(_tool_schema(tool, exposed_name=exposed))
+    return schemas
+
+
+def register_mcp_tools(
+    registry: Any,
+    client: MCPClient,
+    *,
+    prefix: str = "mcp",
+    mutating: bool = True,
+    tools: list[dict[str, Any]] | None = None,
+) -> list[str]:
+    """Register an MCP server's tools into a ``ToolRegistry``.
+
+    MCP tools default to ``mutating=True``: the harness cannot prove a remote
+    tool is read-only, so the plan gate guards them like a workspace edit.
+    """
+    listed = tools if tools is not None else client.list_tools()
+    registered: list[str] = []
+    for tool in listed:
+        name = str(tool.get("name") or "").strip()
+        if not name:
+            continue
+        exposed = f"{prefix}_{name}" if prefix else name
+
+        def handler(arguments: dict[str, Any], _name: str = name) -> dict[str, Any]:
+            return client.call_tool(_name, arguments)
+
+        registry.register(
+            _tool_schema(tool, exposed_name=exposed),
+            handler,
+            source="mcp",
+            mutating=mutating,
+        )
+        registered.append(exposed)
+    return registered
+
+
+__all__ = [
+    "DEFAULT_PROTOCOL_VERSION",
+    "HTTPTransport",
+    "MCPClient",
+    "MCPError",
+    "StdioTransport",
+    "mcp_tool_schemas",
+    "register_mcp_tools",
+]

sid_harness/tools/plan.py

@@ -0,0 +1,138 @@
+"""Plan/todo layer for the SID tool loop (SUB-56).
+
+The gate emits a plan before edits and refuses workspace edits until that plan
+is approved. ``PlanGate`` is consumed by ``ToolRegistry.dispatch``
+(``registry.py``); ``TodoList`` is a small, honest todo store for the session.
+No vendor is named here and no execution path is added — this only decides
+whether the shared loop's mutating tools may run.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Any
+
+TODO_STATUSES = ("pending", "in_progress", "completed", "cancelled")
+
+
+class PlanError(RuntimeError):
+    """A plan or todo action was invalid."""
+
+
+@dataclass
+class Todo:
+    id: str
+    text: str
+    status: str = "pending"
+
+    def as_dict(self) -> dict[str, str]:
+        return {"id": self.id, "text": self.text, "status": self.status}
+
+
+class TodoList:
+    """Ordered todos with a bounded status vocabulary."""
+
+    def __init__(self) -> None:
+        self._items: list[Todo] = []
+        self._seq = 0
+
+    def add(self, text: str) -> Todo:
+        if not isinstance(text, str) or not text.strip():
+            raise PlanError("todo text must be a non-empty string")
+        self._seq += 1
+        todo = Todo(id=f"t{self._seq}", text=text.strip())
+        self._items.append(todo)
+        return todo
+
+    def update(self, todo_id: str, status: str) -> Todo:
+        if status not in TODO_STATUSES:
+            raise PlanError(
+                f"unknown todo status {status!r}; expected one of {', '.join(TODO_STATUSES)}"
+            )
+        for todo in self._items:
+            if todo.id == todo_id:
+                todo.status = status
+                return todo
+        raise PlanError(f"unknown todo {todo_id!r}")
+
+    def items(self) -> list[Todo]:
+        return list(self._items)
+
+    def open_items(self) -> list[Todo]:
+        return [todo for todo in self._items if todo.status in ("pending", "in_progress")]
+
+    def as_dicts(self) -> list[dict[str, str]]:
+        return [todo.as_dict() for todo in self._items]
+
+
+class PlanGate:
+    """Refuse mutating tool calls until a plan has been emitted and approved."""
+
+    def __init__(self, *, require_plan: bool = True) -> None:
+        self.require_plan = require_plan
+        self._plan: list[str] | None = None
+        self._approved = False
+        self._rejected_reason: str | None = None
+        self.todos = TodoList()
+
+    @property
+    def plan(self) -> list[str] | None:
+        return list(self._plan) if self._plan is not None else None
+
+    @property
+    def approved(self) -> bool:
+        return self._approved
+
+    def set_plan(self, steps: Iterable[str]) -> dict[str, Any]:
+        cleaned = [str(step).strip() for step in steps if str(step).strip()]
+        if not cleaned:
+            raise PlanError("a plan needs at least one step")
+        self._plan = cleaned
+        self._approved = False
+        self._rejected_reason = None
+        return self.snapshot()
+
+    def approve(self) -> dict[str, Any]:
+        if self._plan is None:
+            raise PlanError("no plan to approve; call set_plan first")
+        self._approved = True
+        self._rejected_reason = None
+        return self.snapshot()
+
+    def reject(self, reason: str) -> dict[str, Any]:
+        self._approved = False
+        self._rejected_reason = reason.strip() or "plan rejected"
+        return self.snapshot()
+
+    def authorize(self, tool_name: str) -> bool:
+        if not self.require_plan:
+            return True
+        return self._approved
+
+    def refusal(self, tool_name: str) -> str:
+        if self._plan is None:
+            return (
+                f"plan gate: {tool_name} is refused until a plan is emitted and "
+                "approved (call set_plan, then approve)."
+            )
+        if self._rejected_reason:
+            return (
+                f"plan gate: {tool_name} is refused — the plan was rejected "
+                f"({self._rejected_reason})."
+            )
+        return (
+            f"plan gate: {tool_name} is refused until the current plan is "
+            "approved (call approve)."
+        )
+
+    def snapshot(self) -> dict[str, Any]:
+        return {
+            "plan": self.plan,
+            "approved": self._approved,
+            "rejected_reason": self._rejected_reason,
+            "todos": self.todos.as_dicts(),
+        }
+
+
+__all__ = ["PlanError", "PlanGate", "Todo", "TodoList", "TODO_STATUSES"]

sid_harness/tools/registry.py

@@ -0,0 +1,159 @@
+"""Additive tool registry over the shared SID native loop contract.
+
+The loop's tool contract lives in the gateway's ``app.native_agent`` — the four
+base tools, ``_safe_path``, and ``_tool_result``. This module EXTENDS that
+contract; it never forks it:
+
+- ``ToolRegistry.schemas()`` returns the base schemas UNCHANGED (identity-equal
+  to ``native_agent.TOOLS``) followed by registered extension schemas.
+- ``ToolRegistry.dispatch()`` routes every base tool name through
+  ``native_agent._tool_result`` — the one implementation — and only handles
+  extension names itself. There is no second execution engine and no second
+  verify path.
+- A registered name may not shadow a base tool: the safety and execution
+  contract has exactly one owner.
+
+``PlanGate`` (``plan.py``) plugs into ``dispatch`` to refuse workspace edits
+until a plan is approved.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from sid_harness.gateway import native_agent
+
+BASE_TOOL_NAMES: tuple[str, ...] = tuple(
+    schema["function"]["name"] for schema in native_agent.TOOLS
+)
+BASE_TOOL_SCHEMAS: tuple[dict[str, Any], ...] = tuple(native_agent.TOOLS)
+# Every base tool that mutates the workspace, sourced from the shared loop so a
+# new mutating tool can never be added without being gated here too.
+MUTATING_BASE_TOOLS = frozenset(
+    name for name in BASE_TOOL_NAMES if name in native_agent.MUTATING_TOOL_NAMES
+)
+
+ToolHandler = Callable[[dict[str, Any]], Any]
+
+
+class ToolRegistrationError(ValueError):
+    """A tool could not be registered without breaking the shared contract."""
+
+
+@dataclass(frozen=True)
+class RegisteredTool:
+    name: str
+    schema: dict[str, Any]
+    handler: ToolHandler
+    source: str
+    mutating: bool = False
+
+
+class ToolRegistry:
+    """Base SID tools plus registered extensions, dispatched through one seam."""
+
+    def __init__(self, *, gate: Any | None = None) -> None:
+        self._gate = gate
+        self._tools: dict[str, RegisteredTool] = {}
+
+    def set_gate(self, gate: Any | None) -> None:
+        self._gate = gate
+
+    @property
+    def gate(self) -> Any | None:
+        return self._gate
+
+    def register(
+        self,
+        schema: dict[str, Any],
+        handler: ToolHandler,
+        *,
+        source: str = "extension",
+        mutating: bool = False,
+    ) -> RegisteredTool:
+        try:
+            name = schema["function"]["name"]
+        except (KeyError, TypeError) as exc:
+            raise ToolRegistrationError(
+                "tool schema must be an OpenAI-compatible function schema"
+            ) from exc
+        if not isinstance(name, str) or not name:
+            raise ToolRegistrationError("tool schema requires a non-empty function name")
+        if name in BASE_TOOL_NAMES:
+            raise ToolRegistrationError(
+                f"{name!r} shadows a base SID tool; the base contract has one owner"
+            )
+        if name in self._tools:
+            raise ToolRegistrationError(f"tool {name!r} is already registered")
+        if not callable(handler):
+            raise ToolRegistrationError("tool handler must be callable")
+        tool = RegisteredTool(
+            name=name,
+            schema=schema,
+            handler=handler,
+            source=source,
+            mutating=mutating,
+        )
+        self._tools[name] = tool
+        return tool
+
+    def schemas(self) -> list[dict[str, Any]]:
+        """Base schemas (unchanged) followed by extension schemas."""
+        return [*native_agent.TOOLS, *(tool.schema for tool in self._tools.values())]
+
+    def names(self) -> list[str]:
+        return [*BASE_TOOL_NAMES, *self._tools]
+
+    def extension_names(self) -> list[str]:
+        return list(self._tools)
+
+    def is_mutating(self, name: str) -> bool:
+        if name in MUTATING_BASE_TOOLS:
+            return True
+        tool = self._tools.get(name)
+        return bool(tool and tool.mutating)
+
+    def dispatch(
+        self,
+        name: str,
+        arguments: Any,
+        files: dict[str, str],
+        run_tests: Any,
+    ) -> Any:
+        """Route one tool call: base tools to the shared implementation, else here."""
+        if name in BASE_TOOL_NAMES:
+            if self.is_mutating(name) and not self._authorized(name):
+                return {"error": self._refusal(name)}
+            return native_agent._tool_result(name, arguments, files, run_tests)
+        tool = self._tools.get(name)
+        if tool is None:
+            return {"error": f"unknown tool: {name}"}
+        if tool.mutating and not self._authorized(name):
+            return {"error": self._refusal(name)}
+        try:
+            return tool.handler(arguments if isinstance(arguments, dict) else {})
+        except Exception as exc:
+            return {"error": f"tool failed: {type(exc).__name__}: {exc}"}
+
+    def _authorized(self, name: str) -> bool:
+        if self._gate is None:
+            return True
+        return bool(self._gate.authorize(name))
+
+    def _refusal(self, name: str) -> str:
+        if self._gate is None:
+            return f"tool {name} is not authorized"
+        return str(self._gate.refusal(name))
+
+
+__all__ = [
+    "BASE_TOOL_NAMES",
+    "BASE_TOOL_SCHEMAS",
+    "MUTATING_BASE_TOOLS",
+    "RegisteredTool",
+    "ToolHandler",
+    "ToolRegistrationError",
+    "ToolRegistry",
+]