turnloop 0.1.0__py3-none-any.whl

turnloop/hooks/runner.py

@@ -0,0 +1,221 @@
+"""Hooks: user-configured commands that run at defined points.
+
+The protocol is JSON on stdin, and three ways to respond:
+
+* exit 0                    — proceed. stdout is ignored unless it is JSON.
+* exit 2                    — block. stderr becomes the reason the model is told.
+* exit 0 with JSON stdout   — structured control:
+      {"decision": "block"|"approve", "reason": ..., "additionalContext": ...}
+
+Two rules that matter. Hooks run through the same shell resolution as the Bash
+tool, so a hook written as a POSIX one-liner does not hit the WSL stub on Windows
+either. And a hook that crashes, hangs or writes garbage is logged and ignored: a
+broken hook must not be able to take the session down with it.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from dataclasses import dataclass, field
+from fnmatch import fnmatchcase
+from pathlib import Path
+from typing import Any
+
+import anyio
+
+from turnloop.config import HookSpec, Settings
+from turnloop.tools.shell import child_env, decode_output, kill_tree, resolve_shell, spawn_kwargs
+
+HOOK_EVENTS = (
+    "SessionStart",
+    "UserPromptSubmit",
+    "PreToolUse",
+    "PostToolUse",
+    "Stop",
+    "SubagentStop",
+    "PreCompact",
+    "SessionEnd",
+)
+
+
+@dataclass
+class HookOutcome:
+    blocked: bool = False
+    reason: str = ""
+    additional_context: str = ""
+    outputs: list[str] = field(default_factory=list)
+
+
+class HookRunner:
+    def __init__(self, settings: Settings, cwd: Path, session_id: str = ""):
+        self.settings = settings
+        self.cwd = cwd
+        self.session_id = session_id
+        self.log: list[dict] = []
+
+    # --- event entry points ------------------------------------------------
+
+    async def run_pre_tool(self, tool_name: str, args, ctx) -> HookOutcome | None:
+        payload = {
+            "event": "PreToolUse",
+            "tool_name": tool_name,
+            "tool_input": _dump(args),
+            "cwd": str(self.cwd),
+            "session_id": self.session_id,
+        }
+        return await self._run_event("PreToolUse", payload, matcher_value=tool_name)
+
+    async def run_post_tool(self, tool_name: str, args, output, ctx) -> HookOutcome | None:
+        payload = {
+            "event": "PostToolUse",
+            "tool_name": tool_name,
+            "tool_input": _dump(args),
+            "tool_output": (output.content or "")[:8_000],
+            "is_error": output.is_error,
+            "cwd": str(self.cwd),
+            "session_id": self.session_id,
+        }
+        return await self._run_event("PostToolUse", payload, matcher_value=tool_name)
+
+    async def run_user_prompt(self, prompt: str, session) -> HookOutcome | None:
+        payload = {
+            "event": "UserPromptSubmit",
+            "prompt": prompt,
+            "cwd": str(self.cwd),
+            "session_id": session.session_id,
+        }
+        return await self._run_event("UserPromptSubmit", payload)
+
+    async def run_stop(self, session, stop_reason: str) -> HookOutcome | None:
+        payload = {
+            "event": "Stop",
+            "stop_reason": stop_reason,
+            "turn": session.turn,
+            "session_id": session.session_id,
+        }
+        return await self._run_event("Stop", payload)
+
+    async def run_session_event(self, event: str, extra: dict | None = None) -> HookOutcome | None:
+        payload = {"event": event, "cwd": str(self.cwd), "session_id": self.session_id}
+        payload.update(extra or {})
+        return await self._run_event(event, payload)
+
+    # --- execution ---------------------------------------------------------
+
+    async def _run_event(self, event: str, payload: dict,
+                         matcher_value: str | None = None) -> HookOutcome | None:
+        matchers = self.settings.hooks.get(event) or []
+        if not matchers:
+            return None
+
+        outcome = HookOutcome()
+        for matcher in matchers:
+            if matcher_value is not None and not _matches(matcher.matcher, matcher_value):
+                continue
+            for spec in matcher.hooks:
+                result = await self._run_one(spec, payload, event)
+                if result is None:
+                    continue
+                if result.blocked:
+                    return result
+                if result.additional_context:
+                    outcome.additional_context += (
+                        ("\n" if outcome.additional_context else "") + result.additional_context
+                    )
+                outcome.outputs.extend(result.outputs)
+        return outcome
+
+    async def _run_one(self, spec: HookSpec, payload: dict, event: str) -> HookOutcome | None:
+        try:
+            shell = resolve_shell(self.settings.bash.shell)
+        except Exception as exc:  # noqa: BLE001
+            self._record(event, spec.command, error=f"no shell: {exc}")
+            return None
+
+        stdin_data = json.dumps(payload, default=str).encode("utf-8")
+        argv = shell.argv(spec.command)
+
+        try:
+            process = await anyio.open_process(
+                argv,
+                cwd=str(self.cwd),
+                env=child_env({"TURNLOOP_HOOK_EVENT": event}),
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                **spawn_kwargs(),
+            )
+        except OSError as exc:
+            self._record(event, spec.command, error=str(exc))
+            return None
+
+        stdout = b""
+        stderr = b""
+        code: int | None = None
+        try:
+            with anyio.fail_after(spec.timeout):
+                if process.stdin is not None:
+                    await process.stdin.send(stdin_data)
+                    await process.stdin.aclose()
+                if process.stdout is not None:
+                    async for chunk in process.stdout:
+                        stdout += chunk
+                if process.stderr is not None:
+                    async for chunk in process.stderr:
+                        stderr += chunk
+                code = await process.wait()
+        except TimeoutError:
+            kill_tree(process.pid)
+            self._record(event, spec.command, error=f"timed out after {spec.timeout}s")
+            return None
+        except Exception as exc:  # noqa: BLE001 - a broken hook is never fatal
+            self._record(event, spec.command, error=str(exc))
+            return None
+        finally:
+            with anyio.CancelScope(shield=True):
+                try:
+                    await process.aclose()
+                except Exception:  # noqa: BLE001
+                    pass
+
+        out_text = decode_output(stdout).strip()
+        err_text = decode_output(stderr).strip()
+        self._record(event, spec.command, code=code, stdout=out_text[:2_000], stderr=err_text[:2_000])
+
+        # Exit code 2 is the documented "block" signal.
+        if code == 2:
+            return HookOutcome(blocked=True, reason=err_text or "blocked by hook")
+
+        if out_text.startswith("{"):
+            try:
+                data = json.loads(out_text)
+            except json.JSONDecodeError:
+                return HookOutcome(outputs=[out_text])
+            decision = str(data.get("decision", "")).lower()
+            return HookOutcome(
+                blocked=decision == "block",
+                reason=str(data.get("reason", "")),
+                additional_context=str(data.get("additionalContext", "")),
+                outputs=[out_text],
+            )
+
+        return HookOutcome(outputs=[out_text] if out_text else [])
+
+    def _record(self, event: str, command: str, **rest: Any) -> None:
+        entry = {"event": event, "command": command, **rest}
+        self.log.append(entry)
+
+
+def _matches(pattern: str, value: str) -> bool:
+    if pattern in ("", "*"):
+        return True
+    # A comma-separated list is more natural than several matcher blocks.
+    return any(fnmatchcase(value, part.strip()) for part in pattern.split(",") if part.strip())
+
+
+def _dump(args) -> dict:
+    try:
+        return json.loads(args.model_dump_json())
+    except Exception:  # noqa: BLE001
+        return {"repr": str(args)}

turnloop/mcp/adapter.py

@@ -0,0 +1,109 @@
+"""Wrapping MCP tools as native Tool subclasses.
+
+The `Args` model is generated at runtime from the server's JSON Schema, so an MCP
+tool validates exactly like a builtin and produces the same readable error results.
+
+When a schema cannot be turned into a model — and third-party schemas are often
+wrong — the fallback is a permissive passthrough rather than a crash. A badly
+written server should cost its own tool's validation, not the whole startup.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, create_model
+
+from turnloop.config import Verbosity
+from turnloop.mcp.client import MCPClient, MCPTool
+from turnloop.tools.base import Tool, ToolContext, ToolOutput
+
+_JSON_TO_PYTHON = {
+    "string": str,
+    "integer": int,
+    "number": float,
+    "boolean": bool,
+    "object": dict,
+    "array": list,
+}
+
+
+class PassthroughArgs(BaseModel):
+    """Accepts anything. Used when a server's schema is unusable."""
+
+    model_config = ConfigDict(extra="allow")
+
+
+def build_args_model(tool: MCPTool) -> type[BaseModel]:
+    schema = tool.input_schema or {}
+    properties = schema.get("properties")
+    if not isinstance(properties, dict) or not properties:
+        return PassthroughArgs
+
+    required = set(schema.get("required") or [])
+    fields: dict[str, Any] = {}
+
+    for name, spec in properties.items():
+        if not isinstance(spec, dict) or not name.isidentifier():
+            return PassthroughArgs
+        annotation = _JSON_TO_PYTHON.get(str(spec.get("type", "")), Any)
+        description = str(spec.get("description", ""))[:400]
+        if name in required:
+            fields[name] = (annotation, Field(description=description))
+        else:
+            fields[name] = (annotation | None, Field(default=None, description=description))
+
+    try:
+        return create_model(f"MCP_{tool.server}_{tool.name}_Args", **fields)
+    except Exception:  # noqa: BLE001
+        return PassthroughArgs
+
+
+class MCPToolAdapter(Tool):
+    # MCP tools are assumed to mutate: the protocol has no read-only annotation
+    # that can be trusted, and guessing permissively would put unaudited
+    # third-party code inside plan mode.
+    read_only = False
+    parallel_safe = False
+
+    def __init__(self, tool: MCPTool, client: MCPClient):
+        self.tool = tool
+        self.client = client
+        self.name = tool.qualified  # type: ignore[misc]
+        self.Args = build_args_model(tool)  # type: ignore[misc]
+        self.timeout_s = client.config.timeout_s  # type: ignore[misc]
+
+    def description(self, verbosity: Verbosity = "normal") -> str:
+        base = self.tool.description or f"Tool {self.tool.name} from the {self.tool.server} MCP server."
+        if verbosity == "terse":
+            return base.split("\n\n")[0][:300]
+        return base
+
+    def permission_target(self, args) -> str:
+        return self.tool.name
+
+    def summary(self, args) -> str:
+        return f"{self.tool.server}: {self.tool.name}"
+
+    async def run(self, args, ctx: ToolContext) -> ToolOutput:
+        if ctx.readonly:
+            return ToolOutput.error(
+                "plan mode is read-only, and MCP tools are treated as mutating "
+                "because the protocol does not declare otherwise."
+            )
+        payload = args.model_dump(exclude_none=True) if isinstance(args, BaseModel) else dict(args)
+        text, is_error = await self.client.call_tool(self.tool.name, payload)
+        return ToolOutput(
+            content=text,
+            is_error=is_error,
+            display=f"{self.tool.server}:{self.tool.name}",
+            metrics={"mcp_server": self.tool.server, "mcp_tool": self.tool.name},
+        )
+
+
+def adapters_for(manager) -> list[MCPToolAdapter]:
+    out: list[MCPToolAdapter] = []
+    for client in manager.clients.values():
+        for tool in client.tools:
+            out.append(MCPToolAdapter(tool, client))
+    return out

turnloop/mcp/client.py

@@ -0,0 +1,299 @@
+"""Model Context Protocol client: JSON-RPC 2.0 over stdio or SSE.
+
+Hand-rolled rather than taking the SDK, for the same reason the LLM providers are:
+the protocol surface this needs is `initialize`, `tools/list`, `tools/call` and
+notification handling, which is about 150 lines, and owning it means a third-party
+server behaving badly is a problem we can contain rather than one that surfaces as
+an SDK exception mid-turn.
+
+The containment rule: **a dead or misbehaving MCP server degrades to "that tool is
+unavailable" and never blocks the agent loop.** Connections are lazy, every call is
+bounded by a timeout, and a server whose schema cannot be parsed simply contributes
+no tools.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from dataclasses import dataclass, field
+from typing import Any
+
+import anyio
+import httpx
+
+from turnloop.config import MCPServerConfig
+from turnloop.providers.sse import iter_sse
+from turnloop.tools.shell import child_env
+
+PROTOCOL_VERSION = "2025-06-18"
+CLIENT_INFO = {"name": "turnloop", "version": "0.1.0"}
+
+
+@dataclass
+class MCPTool:
+    name: str  # the server's own name, unprefixed
+    description: str
+    input_schema: dict
+    server: str
+
+    @property
+    def qualified(self) -> str:
+        return f"mcp__{self.server}__{self.name}"
+
+
+@dataclass
+class MCPClient:
+    name: str
+    config: MCPServerConfig
+    tools: list[MCPTool] = field(default_factory=list)
+    connected: bool = False
+    error: str | None = None
+
+    _process: Any = None
+    _http: httpx.AsyncClient | None = None
+    _endpoint: str | None = None
+    _next_id: int = 0
+    _lock: Any = None
+
+    def __post_init__(self) -> None:
+        self._lock = anyio.Lock()
+
+    # --- lifecycle ---------------------------------------------------------
+
+    async def connect(self) -> bool:
+        """Idempotent, lazy, and never raises.
+
+        Returns False on failure and records why, so `/mcp` can show the reason
+        instead of the user discovering it as a missing tool.
+        """
+        if self.connected:
+            return True
+        try:
+            with anyio.fail_after(self.config.timeout_s):
+                if self.config.transport == "stdio":
+                    await self._connect_stdio()
+                else:
+                    await self._connect_sse()
+                await self._initialize()
+                await self._load_tools()
+            self.connected = True
+            self.error = None
+            return True
+        except Exception as exc:  # noqa: BLE001 - containment is the point
+            self.error = f"{type(exc).__name__}: {exc}"
+            await self.aclose()
+            return False
+
+    async def _connect_stdio(self) -> None:
+        if not self.config.command:
+            raise ValueError("stdio transport requires `command`")
+        argv = [self.config.command, *self.config.args]
+        self._process = await anyio.open_process(
+            argv,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,  # servers log freely to stderr; not our business
+            env=child_env(self.config.env),
+        )
+
+    async def _connect_sse(self) -> None:
+        if not self.config.url:
+            raise ValueError("sse transport requires `url`")
+        self._http = httpx.AsyncClient(
+            timeout=httpx.Timeout(self.config.timeout_s, connect=10.0),
+            headers=self.config.headers,
+        )
+        # The SSE transport advertises its POST endpoint in an `endpoint` event.
+        self._endpoint = self.config.url.rstrip("/") + "/message"
+
+    async def aclose(self) -> None:
+        if self._process is not None:
+            try:
+                self._process.terminate()
+            except Exception:  # noqa: BLE001
+                pass
+            try:
+                await self._process.aclose()
+            except Exception:  # noqa: BLE001
+                pass
+            self._process = None
+        if self._http is not None:
+            await self._http.aclose()
+            self._http = None
+        self.connected = False
+
+    # --- protocol ----------------------------------------------------------
+
+    async def _initialize(self) -> None:
+        await self._request(
+            "initialize",
+            {
+                "protocolVersion": PROTOCOL_VERSION,
+                "capabilities": {"tools": {}},
+                "clientInfo": CLIENT_INFO,
+            },
+        )
+        await self._notify("notifications/initialized", {})
+
+    async def _load_tools(self) -> None:
+        result = await self._request("tools/list", {})
+        self.tools = []
+        for entry in (result or {}).get("tools", []):
+            schema = entry.get("inputSchema") or {"type": "object", "properties": {}}
+            self.tools.append(
+                MCPTool(
+                    name=entry.get("name", ""),
+                    description=(entry.get("description") or "").strip(),
+                    input_schema=schema,
+                    server=self.name,
+                )
+            )
+
+    async def call_tool(self, tool: str, arguments: dict) -> tuple[str, bool]:
+        """Call a tool. Returns (text, is_error) — never raises."""
+        if not self.connected and not await self.connect():
+            return (f"MCP server {self.name!r} is unavailable: {self.error}", True)
+        try:
+            with anyio.fail_after(self.config.timeout_s):
+                result = await self._request(
+                    "tools/call", {"name": tool, "arguments": arguments}
+                )
+        except TimeoutError:
+            return (f"MCP call {self.name}/{tool} timed out", True)
+        except Exception as exc:  # noqa: BLE001
+            self.connected = False  # force a reconnect next time
+            return (f"MCP call {self.name}/{tool} failed: {exc}", True)
+
+        return _render_result(result or {})
+
+    # --- transport ---------------------------------------------------------
+
+    async def _request(self, method: str, params: dict) -> dict | None:
+        async with self._lock:
+            self._next_id += 1
+            message = {
+                "jsonrpc": "2.0",
+                "id": self._next_id,
+                "method": method,
+                "params": params,
+            }
+            if self._process is not None:
+                return await self._stdio_roundtrip(message)
+            return await self._http_roundtrip(message)
+
+    async def _notify(self, method: str, params: dict) -> None:
+        message = {"jsonrpc": "2.0", "method": method, "params": params}
+        if self._process is not None:
+            await self._write_line(message)
+        elif self._http is not None and self._endpoint is not None:
+            await self._http.post(self._endpoint, json=message)
+
+    async def _write_line(self, message: dict) -> None:
+        assert self._process is not None and self._process.stdin is not None
+        await self._process.stdin.send((json.dumps(message) + "\n").encode("utf-8"))
+
+    async def _stdio_roundtrip(self, message: dict) -> dict | None:
+        await self._write_line(message)
+        assert self._process is not None and self._process.stdout is not None
+
+        buffer = b""
+        target_id = message["id"]
+        async for chunk in self._process.stdout:
+            buffer += chunk
+            while b"\n" in buffer:
+                line, buffer = buffer.split(b"\n", 1)
+                if not line.strip():
+                    continue
+                try:
+                    payload = json.loads(line.decode("utf-8", errors="replace"))
+                except json.JSONDecodeError:
+                    continue  # some servers print banners to stdout
+                if payload.get("id") != target_id:
+                    continue  # a notification or an unrelated response
+                if error := payload.get("error"):
+                    raise RuntimeError(error.get("message", str(error)))
+                return payload.get("result")
+        raise RuntimeError("the MCP server closed its output stream")
+
+    async def _http_roundtrip(self, message: dict) -> dict | None:
+        assert self._http is not None and self._endpoint is not None
+        response = await self._http.post(self._endpoint, json=message)
+        response.raise_for_status()
+
+        content_type = response.headers.get("content-type", "")
+        if "text/event-stream" in content_type:
+            async def lines():
+                for line in response.text.splitlines():
+                    yield line
+
+            async for frame in iter_sse(lines()):
+                payload = frame.json()
+                if payload and payload.get("id") == message["id"]:
+                    if error := payload.get("error"):
+                        raise RuntimeError(error.get("message", str(error)))
+                    return payload.get("result")
+            return None
+
+        payload = response.json()
+        if error := payload.get("error"):
+            raise RuntimeError(error.get("message", str(error)))
+        return payload.get("result")
+
+
+def _render_result(result: dict) -> tuple[str, bool]:
+    """Flatten MCP content blocks into text the model can read."""
+    is_error = bool(result.get("isError"))
+    parts: list[str] = []
+    for item in result.get("content") or []:
+        kind = item.get("type")
+        if kind == "text":
+            parts.append(item.get("text", ""))
+        elif kind == "resource":
+            resource = item.get("resource") or {}
+            parts.append(resource.get("text") or f"(resource: {resource.get('uri', '?')})")
+        elif kind == "image":
+            parts.append(f"(image: {item.get('mimeType', 'unknown')}, not displayed)")
+        else:
+            parts.append(json.dumps(item)[:2_000])
+    if not parts and (structured := result.get("structuredContent")):
+        parts.append(json.dumps(structured, indent=2)[:8_000])
+    return ("\n".join(p for p in parts if p) or "(no content)", is_error)
+
+
+class MCPManager:
+    """Owns every configured server and hands their tools to the registry."""
+
+    def __init__(self, servers: dict[str, MCPServerConfig]):
+        self.clients = {
+            name: MCPClient(name=name, config=cfg)
+            for name, cfg in servers.items()
+            if cfg.enabled
+        }
+
+    async def connect_all(self) -> dict[str, bool]:
+        results: dict[str, bool] = {}
+
+        async def one(name: str, client: MCPClient) -> None:
+            results[name] = await client.connect()
+
+        async with anyio.create_task_group() as tg:
+            for name, client in self.clients.items():
+                tg.start_soon(one, name, client)
+        return results
+
+    def all_tools(self) -> list[MCPTool]:
+        return [tool for client in self.clients.values() for tool in client.tools]
+
+    async def aclose(self) -> None:
+        for client in self.clients.values():
+            await client.aclose()
+
+    def status(self) -> list[tuple[str, str]]:
+        rows = []
+        for name, client in self.clients.items():
+            if client.connected:
+                rows.append((name, f"{len(client.tools)} tool(s)"))
+            else:
+                rows.append((name, f"unavailable: {client.error or 'not connected'}"))
+        return rows