pulse-coding-agent 0.1.0__py3-none-any.whl

pulse/interactive.py

@@ -0,0 +1,234 @@
+"""Responsive terminal input for the interactive Pulse shell."""
+
+from __future__ import annotations
+
+import argparse
+import shlex
+from collections.abc import Iterable
+from pathlib import Path
+
+from prompt_toolkit import PromptSession
+from prompt_toolkit.auto_suggest import AutoSuggestFromHistory
+from prompt_toolkit.completion import Completer, Completion
+from prompt_toolkit.document import Document
+from prompt_toolkit.formatted_text import HTML, FormattedText
+from prompt_toolkit.history import FileHistory, InMemoryHistory
+from prompt_toolkit.input import Input
+from prompt_toolkit.key_binding import KeyBindings
+from prompt_toolkit.output import Output
+from prompt_toolkit.shortcuts import CompleteStyle
+from prompt_toolkit.styles import Style
+
+_SHELL_COMMAND_HELP = {
+    "help": "Show all Pulse commands and usage examples.",
+    "clear": "Clear the terminal screen.",
+    "exit": "End the interactive Pulse session.",
+}
+_ROOT_COMMAND_PRIORITY = ("help", "status", "model", "keys", "clear", "exit")
+
+_STYLE = Style.from_dict(
+    {
+        "prompt": "bold ansicyan",
+        "conversation": "ansibrightblack",
+        "bottom-toolbar": "bg:#20242b #aeb6c2",
+        "completion-menu.completion": "bg:#20242b #d7dae0",
+        "completion-menu.completion.current": "bg:#146b8c #ffffff bold",
+        "completion-menu.meta.completion": "bg:#20242b #8f9aa8",
+        "completion-menu.meta.completion.current": "bg:#146b8c #ffffff",
+    }
+)
+
+
+def _subparsers(parser: argparse.ArgumentParser) -> argparse._SubParsersAction | None:
+    return next(
+        (action for action in parser._actions if isinstance(action, argparse._SubParsersAction)),
+        None,
+    )
+
+
+def _command_help(action: argparse._SubParsersAction) -> dict[str, str]:
+    return {
+        choice.dest: choice.help or ""
+        for choice in action._choices_actions
+    }
+
+
+class SlashCommandCompleter(Completer):
+    """Complete the live argparse command tree after a leading slash."""
+
+    def __init__(self, parser: argparse.ArgumentParser) -> None:
+        self.parser = parser
+
+    def get_completions(self, document: Document, complete_event: object) -> Iterable[Completion]:
+        del complete_event
+        raw = document.text_before_cursor
+        if not raw.startswith("/") or "\n" in raw:
+            return
+
+        body = raw[1:]
+        parts = body.split()
+        fragment = "" if body.endswith((" ", "\t")) else (parts[-1] if parts else "")
+        consumed = parts if not fragment else parts[:-1]
+        parser = self.parser
+
+        # Walk through each nested argparse subcommand already entered.
+        index = 0
+        while index < len(consumed):
+            subcommands = _subparsers(parser)
+            token = consumed[index]
+            if subcommands and token in subcommands.choices:
+                parser = subcommands.choices[token]
+            index += 1
+
+        previous = consumed[-1] if consumed else ""
+        for action in parser._actions:
+            if previous in action.option_strings and action.choices:
+                for choice in action.choices:
+                    value = str(choice)
+                    if value.startswith(fragment):
+                        yield Completion(value, start_position=-len(fragment))
+                return
+
+        candidates: dict[str, str] = {}
+        subcommands = _subparsers(parser)
+        if subcommands:
+            command_help = _command_help(subcommands)
+            if parser is self.parser:
+                root_help = {**command_help, **_SHELL_COMMAND_HELP}
+                for command in _ROOT_COMMAND_PRIORITY:
+                    candidates[command] = root_help[command]
+                for command, description in root_help.items():
+                    candidates.setdefault(command, description)
+            else:
+                candidates.update(command_help)
+        if parser is not self.parser:
+            for action in parser._actions:
+                if action.help == argparse.SUPPRESS:
+                    continue
+                for option in action.option_strings:
+                    candidates[option] = action.help or ""
+
+        root_position = parser is self.parser and not consumed
+        for value, description in candidates.items():
+            shown = f"/{value}" if root_position else value
+            typed = raw if root_position else fragment
+            if shown.startswith(typed):
+                yield Completion(
+                    shown,
+                    start_position=-len(typed),
+                    display_meta=description,
+                )
+
+
+def build_key_bindings() -> KeyBindings:
+    """Return shell-like bindings while keeping Enter fast and predictable."""
+    bindings = KeyBindings()
+
+    @bindings.add("enter")
+    def _submit(event: object) -> None:
+        event.current_buffer.validate_and_handle()  # type: ignore[attr-defined]
+
+    @bindings.add("escape", "enter")
+    def _newline(event: object) -> None:
+        event.current_buffer.insert_text("\n")  # type: ignore[attr-defined]
+
+    @bindings.add("c-space")
+    def _complete(event: object) -> None:
+        event.current_buffer.start_completion(select_first=False)  # type: ignore[attr-defined]
+
+    @bindings.add("tab")
+    def _tab_complete(event: object) -> None:
+        buffer = event.current_buffer  # type: ignore[attr-defined]
+        if buffer.complete_state:
+            buffer.complete_next()
+        else:
+            buffer.start_completion(select_first=True)
+
+    @bindings.add("s-tab")
+    def _previous_completion(event: object) -> None:
+        buffer = event.current_buffer  # type: ignore[attr-defined]
+        if buffer.complete_state:
+            buffer.complete_previous()
+        else:
+            buffer.start_completion(select_first=True)
+
+    @bindings.add("c-c")
+    def _cancel(event: object) -> None:
+        buffer = event.current_buffer  # type: ignore[attr-defined]
+        if buffer.text:
+            buffer.reset()
+        else:
+            event.app.exit(exception=KeyboardInterrupt)  # type: ignore[attr-defined]
+
+    return bindings
+
+
+class InteractivePrompt:
+    """A reusable, testable prompt session with completion and safe history."""
+
+    def __init__(
+        self,
+        workspace: Path,
+        parser: argparse.ArgumentParser,
+        *,
+        input: Input | None = None,
+        output: Output | None = None,
+    ) -> None:
+        history_dir = workspace / ".pulse"
+        try:
+            history_dir.mkdir(parents=True, exist_ok=True)
+            history = FileHistory(str(history_dir / "history"))
+        except OSError:
+            history = InMemoryHistory()
+
+        self.session: PromptSession[str] = PromptSession(
+            completer=SlashCommandCompleter(parser),
+            history=history,
+            auto_suggest=AutoSuggestFromHistory(),
+            key_bindings=build_key_bindings(),
+            style=_STYLE,
+            complete_while_typing=True,
+            complete_in_thread=False,
+            complete_style=CompleteStyle.COLUMN,
+            reserve_space_for_menu=12,
+            # prompt-toolkit disables live completion when history-prefix
+            # search is enabled. Ctrl-R and ordinary Up/Down history remain
+            # available without this conflicting option.
+            enable_history_search=False,
+            multiline=True,
+            prompt_continuation=lambda width, line, wrap: " " * max(0, width - 2) + "· ",
+            bottom_toolbar=HTML(
+                " <b>Tab</b> complete  <b>↑↓</b> history  <b>Ctrl-R</b> search  "
+                "<b>Alt-Enter</b> newline  <b>Ctrl-C</b> clear  <b>/help</b> commands "
+            ),
+            input=input,
+            output=output,
+        )
+
+    def read(self, conversation: str) -> str:
+        label = conversation[:28]
+        return self.session.prompt(
+            FormattedText(
+                [
+                    ("class:prompt", "pulse"),
+                    ("class:conversation", f" [{label}]"),
+                    ("", "> "),
+                ]
+            )
+        ).strip()
+
+
+def parse_slash_command(value: str) -> list[str]:
+    """Parse a quoted slash command without shell execution or path mangling."""
+    if not value.startswith("/"):
+        raise ValueError("Interactive commands must start with '/'.")
+    try:
+        lexer = shlex.shlex(value[1:], posix=True)
+        lexer.whitespace_split = True
+        lexer.commenters = ""
+        # A backslash is a path separator in a cross-platform project CLI, not
+        # a shell escape. Quoting remains available for arguments with spaces.
+        lexer.escape = ""
+        return list(lexer)
+    except ValueError as error:
+        raise ValueError(f"Invalid command quoting: {error}") from error

pulse/mcp/__init__.py

@@ -0,0 +1,4 @@
+from pulse.mcp.client import MCPClientManager
+from pulse.mcp.local_tools import LocalToolLoader
+
+__all__ = ["LocalToolLoader", "MCPClientManager"]

pulse/mcp/client.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import shlex
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+from pulse.subprocesses import isolated_process_kwargs, terminate_process
+from pulse.tool_registry import ToolInvocation, ToolRegistry, ToolResult
+
+MCP_MAX_CONFIG_BYTES = 1_048_576
+MCP_MAX_TOOL_NAME_CHARS = 128
+
+
+def _split_stdio_command(command: str) -> list[str]:
+    try:
+        parts = shlex.split(command, posix=False)
+    except ValueError:
+        return []
+    return [part for part in parts if part]
+
+
+def _is_loopback_http_endpoint(endpoint: str) -> bool:
+    parsed = urlparse(endpoint)
+    if parsed.scheme not in {"http", "https"}:
+        return False
+    host = (parsed.hostname or "").lower()
+    return host in {"127.0.0.1", "::1", "localhost"}
+
+
+class _MCPTool:
+    """An async tool_registry-compatible wrapper around an MCP server tool definition."""
+
+    requires_permission = True
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        server_name: str,
+        transport: str,
+        endpoint: str,
+    ) -> None:
+        self.name = name
+        self.description = description
+        self._server_name = server_name
+        self._transport = transport
+        self._endpoint = endpoint
+
+    def matches(self, invocation: ToolInvocation) -> bool:
+        return invocation.name == self.name
+
+    async def execute(self, invocation: ToolInvocation) -> ToolResult:
+        params = dict(invocation.arguments)
+        if self._transport == "stdio":
+            return await self._call_stdio(params)
+        return await self._call_http(params)
+
+    async def _call_stdio(self, params: dict[str, Any]) -> ToolResult:
+        cmd = _split_stdio_command(self._endpoint)
+        if not cmd:
+            return ToolResult("MCP stdio command is invalid.", metadata={"error": "invalid_command"})
+        payload = json.dumps({"method": self.name, "params": params}) + "\n"
+        process: asyncio.subprocess.Process | None = None
+        try:
+            process = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdin=asyncio.subprocess.PIPE,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.DEVNULL,
+                **isolated_process_kwargs(),
+            )
+            stdout, _ = await asyncio.wait_for(
+                process.communicate(payload.encode()),
+                timeout=30,
+            )
+            data = json.loads(stdout.decode(errors="replace"))
+            content = data.get("result") or data.get("content") or str(data)
+            return ToolResult(str(content), metadata={"server": self._server_name, "transport": "stdio"})
+        except TimeoutError:
+            await terminate_process(process)
+            return ToolResult(f"MCP tool '{self.name}' timed out.", metadata={"error": "timeout"})
+        except asyncio.CancelledError:
+            await terminate_process(process)
+            raise
+        # Intentionally broad to isolate execution boundaries and prevent crashes.
+        except Exception:  # noqa: BLE001
+            return ToolResult("MCP tool failed.", metadata={"error": "execution_failed"})
+
+    async def _call_http(self, params: dict[str, Any]) -> ToolResult:
+        try:
+            import httpx
+        except ImportError:
+            return ToolResult("httpx is required for HTTP MCP transport.", metadata={"error": "missing_dependency"})
+        if not _is_loopback_http_endpoint(self._endpoint):
+            return ToolResult("MCP HTTP endpoint must be loopback.", metadata={"error": "endpoint_not_allowed"})
+
+        payload = {"jsonrpc": "2.0", "id": 1, "method": self.name, "params": params}
+        try:
+            async with httpx.AsyncClient(timeout=30) as client:
+                response = await client.post(self._endpoint, json=payload)
+                data = response.json()
+                content = data.get("result") or data.get("content") or str(data)
+                return ToolResult(str(content), metadata={"server": self._server_name, "transport": "http"})
+        # Intentionally broad to isolate execution boundaries and prevent crashes.
+        except Exception:  # noqa: BLE001
+            return ToolResult("MCP tool failed.", metadata={"error": "execution_failed"})
+
+
+class MCPClientManager:
+    """Discovers and connects to standard stdio/HTTP MCP servers defined in agent.config.json under `mcp_servers`.
+
+    Converts external MCP tool definitions into async pulse.tool_registry tool instances.
+    """
+
+    def __init__(self, config_path: Path, registry: ToolRegistry) -> None:
+        self._config_path = config_path
+        self._registry = registry
+
+    def _load_mcp_servers(self) -> list[dict[str, Any]]:
+        if not self._config_path.exists():
+            return []
+        if self._config_path.is_symlink() or self._config_path.stat().st_size > MCP_MAX_CONFIG_BYTES:
+            return []
+        raw: dict[str, Any] = json.loads(self._config_path.read_text(encoding="utf-8"))
+        servers = raw.get("mcp_servers", [])
+        return servers if isinstance(servers, list) else []
+
+    async def discover_and_register_tools(self) -> int:
+        """Probe each configured MCP server for its tool manifest and register all tools.
+
+        Returns the number of tools successfully registered.
+        """
+        servers = self._load_mcp_servers()
+        registered = 0
+        for server in servers:
+            if not isinstance(server, dict):
+                continue
+            server_name = str(server.get("name", "unnamed"))[:MCP_MAX_TOOL_NAME_CHARS]
+            transport = str(server.get("transport", "stdio")).lower()
+            endpoint = str(server.get("endpoint", ""))
+            raw_tools_manifest = server.get("tools", [])
+            tools_manifest = raw_tools_manifest if isinstance(raw_tools_manifest, list) else []
+
+            if not tools_manifest and transport == "http" and endpoint:
+                tools_manifest = await self._probe_http_manifest(endpoint)
+            elif not tools_manifest and transport == "stdio" and endpoint:
+                tools_manifest = await self._probe_stdio_manifest(endpoint)
+
+            for tool_def in tools_manifest:
+                if not isinstance(tool_def, dict):
+                    continue
+                tool_leaf = str(tool_def.get("name", "unknown"))[:MCP_MAX_TOOL_NAME_CHARS]
+                tool_name = f"{server_name}.{tool_leaf}"
+                description = tool_def.get("description", f"MCP tool from {server_name}")
+                tool = _MCPTool(
+                    name=tool_name,
+                    description=description,
+                    server_name=server_name,
+                    transport=transport,
+                    endpoint=endpoint,
+                )
+                try:
+                    self._registry.register(tool)
+                    registered += 1
+                except ValueError:
+                    pass  # Already registered; skip
+
+        return registered
+
+    async def _probe_http_manifest(self, endpoint: str) -> list[dict[str, Any]]:
+        if not _is_loopback_http_endpoint(endpoint):
+            return []
+        try:
+            import httpx
+            async with httpx.AsyncClient(timeout=10) as client:
+                response = await client.get(endpoint.rstrip("/") + "/tools")
+                if response.is_success:
+                    data = response.json()
+                    return data if isinstance(data, list) else data.get("tools", [])
+        # Intentionally broad to isolate execution boundaries and prevent crashes.
+        except Exception:  # noqa: BLE001, S110
+            pass
+        return []
+
+    async def _probe_stdio_manifest(self, command: str) -> list[dict[str, Any]]:
+        cmd = _split_stdio_command(command)
+        if not cmd:
+            return []
+        payload = json.dumps({"method": "tools/list", "params": {}}) + "\n"
+        process: asyncio.subprocess.Process | None = None
+        try:
+            process = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdin=asyncio.subprocess.PIPE,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.DEVNULL,
+                **isolated_process_kwargs(),
+            )
+            stdout, _ = await asyncio.wait_for(process.communicate(payload.encode()), timeout=10)
+            data = json.loads(stdout.decode(errors="replace"))
+            tools = data.get("result", data.get("tools", []))
+            return tools if isinstance(tools, list) else []
+        except TimeoutError:
+            await terminate_process(process)
+            return []
+        except asyncio.CancelledError:
+            await terminate_process(process)
+            raise
+        # Intentionally broad to isolate execution boundaries and prevent crashes.
+        except Exception:  # noqa: BLE001
+            await terminate_process(process)
+            return []

pulse/mcp/local_tools.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+from typing import Any
+
+from pulse.tool_registry import ToolInvocation, ToolRegistry, ToolResult
+
+
+class _DynamicTool:
+    """A tool_registry-compatible wrapper around a dynamically loaded workspace tool script."""
+
+    requires_permission = True
+
+    def __init__(self, name: str, description: str, module: Any) -> None:
+        self.name = name
+        self.description = description
+        self._module = module
+
+    def matches(self, invocation: ToolInvocation) -> bool:
+        return invocation.name == self.name
+
+    async def execute(self, invocation: ToolInvocation) -> ToolResult:
+        try:
+            execute_fn = getattr(self._module, "execute", None)
+            if execute_fn is None:
+                return ToolResult(
+                    f"Tool '{self.name}' has no `execute` function.",
+                    metadata={"error": "missing_execute"},
+                )
+            import asyncio
+            if asyncio.iscoroutinefunction(execute_fn):
+                result = await execute_fn(invocation)
+            else:
+                result = execute_fn(invocation)
+
+            if isinstance(result, ToolResult):
+                return result
+            return ToolResult(str(result))
+        # Intentionally broad to isolate execution boundaries and prevent crashes.
+        except Exception as exc:  # noqa: BLE001
+            return ToolResult(
+                f"Dynamic tool '{self.name}' raised: {exc}",
+                metadata={"error": str(exc)},
+            )
+
+
+class LocalToolLoader:
+    """Automatically scans `.agent/tools/*.py` scripts in the workspace and registers
+    them as dynamically available tools at runtime.
+
+    Each tool script must define:
+    - `NAME: str` — tool identifier
+    - `DESCRIPTION: str` — human-readable description
+    - `execute(invocation: ToolInvocation) -> ToolResult` — sync or async callable
+    """
+
+    def __init__(self, workspace: Path, registry: ToolRegistry) -> None:
+        self._workspace = workspace.resolve()
+        self._registry = registry
+        self._tools_dir = self._workspace / ".agent" / "tools"
+
+    def load(self) -> int:
+        """Scan tools directory, import each script, and register valid tool modules.
+
+        Returns the number of tools successfully loaded.
+        """
+        if not self._tools_dir.exists():
+            return 0
+
+        loaded = 0
+        for script in sorted(self._tools_dir.glob("*.py")):
+            if script.stem.startswith("_"):
+                continue
+            try:
+                module = self._import_module(script)
+                name: str = getattr(module, "NAME", script.stem)
+                description: str = getattr(module, "DESCRIPTION", f"Local tool: {script.stem}")
+
+                if not hasattr(module, "execute"):
+                    continue
+
+                tool = _DynamicTool(name=name, description=description, module=module)
+                try:
+                    self._registry.register(tool)
+                    loaded += 1
+                except ValueError:
+                    pass  # Already registered; skip duplicate
+            # Intentionally broad to isolate execution boundaries and prevent crashes.
+            except Exception:  # noqa: BLE001, S112
+                continue
+
+        return loaded
+
+    @staticmethod
+    def _import_module(script: Path) -> Any:
+        module_name = f"_pulse_local_tool_{script.stem}"
+        spec = importlib.util.spec_from_file_location(module_name, script)
+        if spec is None or spec.loader is None:
+            raise ImportError(f"Cannot load spec for {script}")
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+        spec.loader.exec_module(module)  # type: ignore[union-attr]
+        return module