bareagent-cli 0.1.0__py3-none-any.whl

bareagent/debug/web_viewer.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from queue import Empty
+from socketserver import ThreadingMixIn
+from typing import Any
+from urllib.parse import unquote, urlparse
+
+_VIEWER_HTML = Path(__file__).with_name("viewer.html")
+
+
+class DebugViewerHandler(BaseHTTPRequestHandler):
+    """Serve the debug viewer SPA and read-only interaction APIs."""
+
+    server: DebugViewerServer
+
+    def log_message(self, format: str, *args: Any) -> None:
+        """Silence the default HTTP request logging."""
+
+    def do_GET(self) -> None:
+        path = urlparse(self.path).path
+
+        if path == "/":
+            self._serve_html()
+            return
+
+        if path == "/api/sessions":
+            self._serve_json(self.server.logger.list_sessions())
+            return
+
+        session_prefix = "/api/sessions/"
+        if path.startswith(session_prefix):
+            session_id = unquote(path.removeprefix(session_prefix))
+            if session_id and "/" not in session_id:
+                try:
+                    self._serve_json(self.server.logger.list_interactions(session_id))
+                except ValueError:
+                    self._serve_error(404, "Not Found")
+                return
+
+        interaction_prefix = "/api/interactions/"
+        if path.startswith(interaction_prefix):
+            remainder = path.removeprefix(interaction_prefix)
+            parts = [unquote(part) for part in remainder.split("/", maxsplit=1)]
+            if len(parts) == 2 and parts[0]:
+                session_id, seq_text = parts
+                try:
+                    seq = int(seq_text)
+                except ValueError:
+                    self._serve_error(400, "Invalid seq")
+                    return
+                try:
+                    self._serve_json(
+                        self.server.logger.get_interaction(session_id, seq)
+                    )
+                except ValueError:
+                    self._serve_error(404, "Not Found")
+                return
+
+        if path == "/api/events":
+            self._serve_sse()
+            return
+
+        self._serve_error(404, "Not Found")
+
+    def _serve_html(self) -> None:
+        try:
+            content = _VIEWER_HTML.read_bytes()
+        except OSError:
+            self._serve_error(500, "viewer.html not found")
+            return
+
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(content)))
+        self.end_headers()
+        self.wfile.write(content)
+
+    def _serve_json(self, data: Any) -> None:
+        body = json.dumps(data, ensure_ascii=False, default=str).encode("utf-8")
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _serve_error(self, code: int, message: str) -> None:
+        body = json.dumps({"error": message}, ensure_ascii=False).encode("utf-8")
+        self.send_response(code)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _serve_sse(self) -> None:
+        self.send_response(200)
+        self.send_header("Content-Type", "text/event-stream")
+        self.send_header("Cache-Control", "no-cache")
+        self.send_header("Connection", "keep-alive")
+        self.end_headers()
+
+        subscribe = getattr(self.server.logger, "subscribe_events", None)
+        unsubscribe = getattr(self.server.logger, "unsubscribe_events", None)
+        event_queue: Any = (
+            subscribe() if callable(subscribe) else self.server.logger.event_queue
+        )
+
+        try:
+            while True:
+                try:
+                    event = event_queue.get(timeout=30)
+                    payload = json.dumps(event, ensure_ascii=False, default=str)
+                    self.wfile.write(f"data: {payload}\n\n".encode())
+                except Empty:
+                    self.wfile.write(b": heartbeat\n\n")
+                self.wfile.flush()
+        except (BrokenPipeError, ConnectionResetError, OSError):
+            return
+        finally:
+            if callable(unsubscribe):
+                unsubscribe(event_queue)
+
+
+class DebugViewerServer(ThreadingMixIn, HTTPServer):
+    """HTTP server that exposes an attached interaction logger."""
+
+    daemon_threads = True
+    allow_reuse_address = True
+
+    def __init__(
+        self,
+        logger: Any,
+        port: int = 8321,
+        host: str = "127.0.0.1",
+    ) -> None:
+        self.logger = logger
+        super().__init__((host, port), DebugViewerHandler)
+
+
+def start_viewer(
+    logger: Any,
+    port: int = 8321,
+    host: str = "127.0.0.1",
+) -> tuple[DebugViewerServer, threading.Thread]:
+    """Start the debug viewer on a daemon thread."""
+
+    server = DebugViewerServer(logger, port=port, host=host)
+    thread = threading.Thread(
+        target=server.serve_forever,
+        daemon=True,
+        name="debug-viewer",
+    )
+    thread.start()
+    return server, thread

bareagent/hooks/__init__.py

@@ -0,0 +1,32 @@
+"""User-defined hooks fired around tool execution in the main agent loop.
+
+Users declare ``[[hooks]]`` in ``config.toml`` to run custom shell commands
+before and after a tool call:
+
+- ``PreToolUse`` fires after the permission check passes but before the handler
+  runs. An exit code of 2 intercepts the call (the handler is skipped and the
+  hook's stderr is fed back to the LLM as an error result).
+- ``PostToolUse`` fires after the handler returns successfully, for side effects
+  (e.g. ``ruff format`` after ``write_file``). Its exit code is ignored.
+
+The permission guard remains the security boundary; hooks are a user-configured
+convenience layer (trust-the-config), and they only fire in the main loop —
+sub-agents never run hooks (isolation). Failures are fail-open.
+"""
+
+from __future__ import annotations
+
+from .config import HookEntry, HooksConfig, parse_hooks_config
+from .engine import HookEngine, HookOutcome
+from .errors import HookConfigError
+from .events import HookEvent
+
+__all__ = [
+    "HookConfigError",
+    "HookEngine",
+    "HookEntry",
+    "HookEvent",
+    "HookOutcome",
+    "HooksConfig",
+    "parse_hooks_config",
+]

bareagent/hooks/config.py

@@ -0,0 +1,118 @@
+"""Hook configuration parsing.
+
+Reads a ``[[hooks]]`` array of tables from a TOML-derived dict and returns a
+typed :class:`HooksConfig`. Each entry binds a shell ``command`` to a
+:class:`~bareagent.hooks.events.HookEvent` and an optional precise ``tool`` name
+(omitted = matches every tool).
+
+Graceful degradation policy (mirrors MCP/LSP): a structurally broken document
+(non-list ``hooks``, non-table entry) raises :class:`HookConfigError` so
+``main.py`` can warn and fall back to an empty config. A single *malformed*
+entry (unknown event, blank command) is skipped and recorded in
+:attr:`HooksConfig.skipped`, rather than nuking the whole config — one bad line
+should not disable a user's other working hooks.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import HookConfigError
+from .events import HookEvent
+
+_VALID_EVENTS = frozenset(event.value for event in HookEvent)
+_DEFAULT_TIMEOUT = 30
+
+
+@dataclass(slots=True)
+class HookEntry:
+    """One ``[[hooks]]`` entry: when to fire and what to run."""
+
+    event: str
+    command: str
+    # None => match every tool for this event.
+    tool: str | None = None
+    timeout: int = _DEFAULT_TIMEOUT
+
+
+@dataclass(slots=True)
+class HooksConfig:
+    """Top-level hooks configuration."""
+
+    entries: list[HookEntry] = field(default_factory=list)
+    # Human-readable reasons for entries that were dropped during parsing.
+    skipped: list[str] = field(default_factory=list)
+
+    def matching(self, event: str, tool_name: str) -> list[HookEntry]:
+        """Return entries for *event* whose ``tool`` is None or equals *tool_name*.
+
+        Order is preserved (config declaration order) so hooks fire predictably.
+        """
+        return [
+            entry
+            for entry in self.entries
+            if entry.event == event and (entry.tool is None or entry.tool == tool_name)
+        ]
+
+
+def parse_hooks_config(raw: dict[str, Any]) -> HooksConfig:
+    """Parse a TOML-derived dict into :class:`HooksConfig`.
+
+    Accepts either the full document (where ``hooks`` is a key holding the
+    array of tables) or a bare ``{"hooks": [...]}`` wrapper. Unknown keys on an
+    entry are ignored to stay forward-compatible.
+
+    Raises :class:`HookConfigError` only for structural failures (the document
+    or the ``hooks`` value has the wrong shape). Individual malformed entries
+    are skipped and recorded in :attr:`HooksConfig.skipped`.
+    """
+    if not isinstance(raw, dict):
+        raise HookConfigError(f"hooks config must be a table, got {type(raw).__name__}")
+
+    entries_raw = raw.get("hooks", [])
+    if not isinstance(entries_raw, list):
+        raise HookConfigError("'hooks' must be an array of tables")
+
+    config = HooksConfig()
+    for index, entry in enumerate(entries_raw):
+        if not isinstance(entry, dict):
+            config.skipped.append(f"hooks[{index}] is not a table; skipped")
+            continue
+        parsed = _parse_entry(entry, index, config.skipped)
+        if parsed is not None:
+            config.entries.append(parsed)
+    return config
+
+
+def _parse_entry(entry: dict[str, Any], index: int, skipped: list[str]) -> HookEntry | None:
+    event = entry.get("event")
+    if event not in _VALID_EVENTS:
+        skipped.append(
+            f"hooks[{index}].event must be one of {sorted(_VALID_EVENTS)}, got {event!r}; skipped"
+        )
+        return None
+
+    command = entry.get("command")
+    if not isinstance(command, str) or not command.strip():
+        skipped.append(
+            f"hooks[{index}].command is required and must be a non-empty string; skipped"
+        )
+        return None
+
+    tool = entry.get("tool")
+    if tool is not None and (not isinstance(tool, str) or not tool):
+        skipped.append(f"hooks[{index}].tool must be a non-empty string if provided; skipped")
+        return None
+
+    timeout = entry.get("timeout", _DEFAULT_TIMEOUT)
+    if isinstance(timeout, bool) or not isinstance(timeout, int) or timeout <= 0:
+        skipped.append(f"hooks[{index}].timeout must be a positive integer; skipped")
+        return None
+
+    return HookEntry(
+        event=str(event),
+        command=command,
+        tool=tool,
+        timeout=timeout,
+    )

bareagent/hooks/engine.py

@@ -0,0 +1,197 @@
+"""Hook execution engine.
+
+Matches configured hooks against a tool call and runs them as cross-platform
+subprocesses, passing the call context as a single JSON object on stdin. The
+control protocol is exit-code based (PRD D2):
+
+- ``PreToolUse`` exit 2 -> intercept: the handler is skipped and the hook's
+  stderr is returned to the LLM as an error result.
+- exit 0 -> allow.
+- any other non-zero exit -> non-blocking warning, then allow.
+
+Failures are fail-open (PRD D3): a spawn error or timeout warns and allows; it
+never blocks the tool or crashes the loop. ``PostToolUse`` hooks run side
+effects only — their exit code never changes the tool result.
+
+This module must NOT import :mod:`bareagent.core.loop` — the engine is *called by* the
+loop, and the reverse dependency would create an import cycle.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from dataclasses import dataclass
+from typing import Any
+
+from bareagent.core.fileutil import stringify
+from bareagent.ui.protocol import UIProtocol
+
+from .config import HookEntry, HooksConfig
+from .events import HookEvent
+
+# Exit code reserved by the Claude-Code-aligned protocol for "intercept".
+_BLOCK_EXIT_CODE = 2
+
+
+@dataclass(slots=True)
+class HookOutcome:
+    """Result of running the PreToolUse hooks for one tool call."""
+
+    block: bool = False
+    reason: str = ""
+
+
+class HookEngine:
+    """Runs PreToolUse / PostToolUse hooks for the main agent loop."""
+
+    def __init__(self, config: HooksConfig, *, console: UIProtocol | None = None) -> None:
+        self._config = config
+        self._console = console
+
+    def run_pre_tool_use(
+        self,
+        tool_name: str,
+        tool_input: dict[str, Any],
+        *,
+        session_id: str,
+        cwd: str,
+    ) -> HookOutcome:
+        """Run matching PreToolUse hooks. First exit-2 hook intercepts the call."""
+        entries = self._config.matching(HookEvent.PRE_TOOL_USE.value, tool_name)
+        if not entries:
+            return HookOutcome()
+
+        payload = {
+            "event": HookEvent.PRE_TOOL_USE.value,
+            "tool_name": tool_name,
+            "tool_input": tool_input,
+            "session_id": session_id,
+            "cwd": cwd,
+        }
+        for entry in entries:
+            result = self._run_one(entry, payload)
+            if result is None:
+                # Spawn failure / timeout -> fail-open, already warned.
+                continue
+            if result.returncode == _BLOCK_EXIT_CODE:
+                reason = (result.stderr or "").strip()
+                return HookOutcome(
+                    block=True,
+                    reason=reason or f"Blocked by PreToolUse hook for {tool_name}.",
+                )
+            if result.returncode != 0:
+                self._warn_non_zero(entry, tool_name, result)
+        return HookOutcome()
+
+    def run_post_tool_use(
+        self,
+        tool_name: str,
+        tool_input: dict[str, Any],
+        tool_output: Any,
+        *,
+        is_error: bool,
+        session_id: str,
+        cwd: str,
+    ) -> None:
+        """Run matching PostToolUse hooks for side effects. Exit codes don't matter."""
+        entries = self._config.matching(HookEvent.POST_TOOL_USE.value, tool_name)
+        if not entries:
+            return
+
+        payload = {
+            "event": HookEvent.POST_TOOL_USE.value,
+            "tool_name": tool_name,
+            "tool_input": tool_input,
+            "session_id": session_id,
+            "cwd": cwd,
+            "tool_output": stringify(tool_output),
+            "is_error": is_error,
+        }
+        for entry in entries:
+            result = self._run_one(entry, payload)
+            if result is None:
+                continue
+            if result.returncode != 0:
+                self._warn_non_zero(entry, tool_name, result)
+
+    def _run_one(
+        self, entry: HookEntry, payload: dict[str, Any]
+    ) -> subprocess.CompletedProcess[str] | None:
+        """Spawn the hook command, feeding *payload* as JSON on stdin.
+
+        Returns the completed process, or ``None`` when the hook failed to run
+        at all (timeout / spawn error) — both fail-open cases (PRD D3).
+        """
+        argv = _build_argv(entry.command)
+        stdin_json = json.dumps(payload, ensure_ascii=False)
+        try:
+            return subprocess.run(
+                argv,
+                input=stdin_json,
+                capture_output=True,
+                timeout=entry.timeout,
+                check=False,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+            )
+        except subprocess.TimeoutExpired:
+            self._warn(
+                f"{entry.event} hook timed out after {entry.timeout}s "
+                f"(command: {entry.command!r}); allowing tool."
+            )
+            return None
+        except (OSError, ValueError) as exc:
+            self._warn(
+                f"{entry.event} hook failed to start ({type(exc).__name__}: {exc}); allowing tool."
+            )
+            return None
+
+    def _warn_non_zero(
+        self,
+        entry: HookEntry,
+        tool_name: str,
+        result: subprocess.CompletedProcess[str],
+    ) -> None:
+        detail = (result.stderr or result.stdout or "").strip()
+        message = (
+            f"{entry.event} hook for {tool_name} exited with code "
+            f"{result.returncode} (non-blocking)."
+        )
+        if detail:
+            message = f"{message} {detail}"
+        self._warn(message)
+
+    def _warn(self, message: str) -> None:
+        if self._console is not None:
+            self._console.print_status(message)
+
+
+def _build_argv(command: str) -> list[str]:
+    """Build the cross-platform shell argv for *command*.
+
+    Mirrors :func:`bareagent.core.handlers.bash.run_bash`: Windows PowerShell with the
+    output encoding forced to UTF-8 so non-ASCII stdout/stderr round-trips, and
+    ``bash -lc`` elsewhere.
+
+    Unlike ``run_bash`` (which only reads ``returncode`` for a status message),
+    the hook control protocol *depends* on the child's exit code, so the
+    PowerShell wrapper appends ``; exit $LASTEXITCODE``. Without it,
+    ``powershell -Command`` returns its own parse/host exit status (typically 0
+    or 1) rather than the command's exit code — which would silently break the
+    exit-2 intercept contract.
+    """
+    if os.name == "nt":
+        windows_prefix = (
+            "try { [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 } catch {}; "
+        )
+        windows_suffix = "; exit $LASTEXITCODE"
+        return [
+            "powershell",
+            "-NoProfile",
+            "-Command",
+            windows_prefix + command + windows_suffix,
+        ]
+    return ["bash", "-lc", command]

bareagent/hooks/errors.py

@@ -0,0 +1,14 @@
+"""Hook error hierarchy.
+
+Only ``HookConfigError`` is raised — at parse time, so ``main.py`` can catch it
+and degrade gracefully (warn + run with an empty :class:`HooksConfig`), mirroring
+the MCP/LSP config-failure fallbacks. Hook *runtime* failures (spawn error,
+timeout, non-zero exit) are never exceptions: they are fail-open per PRD D3 and
+surface as console warnings instead.
+"""
+
+from __future__ import annotations
+
+
+class HookConfigError(Exception):
+    """Raised when the ``[[hooks]]`` configuration is structurally invalid."""

bareagent/hooks/events.py

@@ -0,0 +1,22 @@
+"""Hook event identifiers.
+
+The MVP supports exactly two events (see PRD decision D1):
+
+- ``PreToolUse`` — fired after the permission check passes but *before* the
+  tool handler runs. A hook can intercept the tool (exit code 2).
+- ``PostToolUse`` — fired after the handler returns successfully, before the
+  result is wrapped back to the LLM. A hook may run side effects; its exit code
+  never changes the tool result.
+
+Values match Claude Code's hook event names so that user mental models and
+config snippets carry over.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class HookEvent(StrEnum):
+    PRE_TOOL_USE = "PreToolUse"
+    POST_TOOL_USE = "PostToolUse"

bareagent/lsp/__init__.py

@@ -0,0 +1,63 @@
+"""LSP (Language Server Protocol) client subpackage.
+
+PR1 (this child) delivers the multi-language manager, four Tier-1 tools
+(``lsp_outline`` / ``lsp_definition`` / ``lsp_references`` /
+``lsp_diagnostics``), config parsing, and agent-type integration. UX (REPL
+commands), atexit cleanup, hybrid auto-diagnostics, and the real
+``[lsp]`` extra E2E test land in the sibling child task.
+
+``multilspy`` is an **optional dependency**. Importing this package never
+raises when the extra is missing — the boolean ``MULTILSPY_AVAILABLE`` lets
+callers feature-detect, and :class:`LanguageServerManager` degrades to a
+no-op when the underlying library is unavailable.
+"""
+
+from __future__ import annotations
+
+from .config import LSPConfig, LSPServerConfig, parse_lsp_config
+from .errors import LSPCallError, LSPError, LSPHandshakeError
+from .manager import LanguageServerManager, ServerStatus
+from .tools import (
+    LSP_TOOL_NAMES,
+    LSP_TOOL_SCHEMAS,
+    SEMANTIC_RENAME_TOOL_NAME,
+    SEMANTIC_RENAME_TOOL_SCHEMA,
+    build_lsp_tools,
+)
+from .workspace_edit import apply_workspace_edit
+
+
+def _detect_multilspy() -> bool:
+    """Return True iff ``import multilspy`` succeeds at package-import time.
+
+    The check is done eagerly here so callers can branch on the boolean
+    without paying an import every call. Errors other than ``ImportError``
+    (rare, e.g. a broken install) are treated as "not available".
+    """
+    try:
+        import multilspy  # noqa: F401  # type: ignore
+    except Exception:
+        return False
+    return True
+
+
+MULTILSPY_AVAILABLE: bool = _detect_multilspy()
+
+
+__all__ = [
+    "LSPCallError",
+    "LSPConfig",
+    "LSPError",
+    "LSPHandshakeError",
+    "LSPServerConfig",
+    "LSP_TOOL_NAMES",
+    "LSP_TOOL_SCHEMAS",
+    "SEMANTIC_RENAME_TOOL_NAME",
+    "SEMANTIC_RENAME_TOOL_SCHEMA",
+    "LanguageServerManager",
+    "MULTILSPY_AVAILABLE",
+    "ServerStatus",
+    "apply_workspace_edit",
+    "build_lsp_tools",
+    "parse_lsp_config",
+]