bareagent-cli 0.1.0__py3-none-any.whl

bareagent/core/handlers/file_read.py

@@ -0,0 +1,270 @@
+from __future__ import annotations
+
+import base64
+import json
+from pathlib import Path
+from typing import Any
+
+from bareagent.core.sandbox import safe_path
+
+# Image extension -> Anthropic-supported mime type. The whitelist mirrors
+# ``mcp/registry.py:_SUPPORTED_IMAGE_MIME_TYPES`` so local image reads produce
+# the same internal block shape MCP multimodal results do.
+_IMAGE_EXT_TO_MIME: dict[str, str] = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+}
+
+# Hard cap on image payloads. Aligned with the MCP default
+# ``max_result_binary_bytes`` (5 MiB). Over-limit images return an Error string
+# (D2: ask the user to downscale; we do not auto-resize — that needs Pillow).
+_MAX_IMAGE_BYTES = 5_242_880  # 5 MiB
+
+# Per-output and whole-document length caps for textual renderings (notebook
+# cell outputs, PDF text). Keeps a pathological file from flooding the context.
+_MAX_CELL_OUTPUT_CHARS = 2000
+_MAX_DOCUMENT_CHARS = 200_000
+
+_TRUNCATED_MARKER = "... [truncated]"
+
+
+def run_read(
+    file_path: str,
+    offset: int = 0,
+    limit: int | None = None,
+    *,
+    pages: str | None = None,
+    workspace: Path,
+) -> str | list[dict[str, Any]]:
+    """Read a workspace file, dispatching by extension.
+
+    - Images (.png/.jpg/.jpeg/.gif/.webp) -> ``[text, image]`` content blocks.
+    - PDF (.pdf) -> extracted text (optional ``pages`` range); needs the
+      ``[pdf]`` extra (pypdf).
+    - Notebook (.ipynb) -> text rendering of markdown/code cells + outputs.
+    - Everything else -> the legacy UTF-8 text path with line numbers
+      (``offset`` / ``limit`` slice).
+    """
+    if offset < 0:
+        raise ValueError("offset must be >= 0")
+    if limit is not None and limit < 0:
+        raise ValueError("limit must be >= 0")
+
+    resolved = safe_path(file_path, workspace)
+    suffix = resolved.suffix.lower()
+
+    if suffix in _IMAGE_EXT_TO_MIME:
+        return _read_image(resolved, _IMAGE_EXT_TO_MIME[suffix])
+    if suffix == ".pdf":
+        return _read_pdf(resolved, pages)
+    if suffix == ".ipynb":
+        return _read_notebook(resolved)
+
+    return _read_text(resolved, offset, limit)
+
+
+def _read_text(resolved: Path, offset: int, limit: int | None) -> str:
+    """Read a UTF-8 text file and prefix each line with its line number."""
+    if offset > 0 or limit is not None:
+        # Stream lines to avoid loading the entire file when only a slice is needed.
+        selected: list[str] = []
+        end = None if limit is None else offset + limit
+        with resolved.open(encoding="utf-8") as fh:
+            for idx, line in enumerate(fh):
+                if idx < offset:
+                    continue
+                if end is not None and idx >= end:
+                    break
+                selected.append(line.rstrip("\n\r"))
+    else:
+        selected = resolved.read_text(encoding="utf-8").splitlines()
+
+    return "\n".join(
+        f"{line_number}: {line}" for line_number, line in enumerate(selected, start=offset + 1)
+    )
+
+
+def _read_image(resolved: Path, mime: str) -> str | list[dict[str, Any]]:
+    """Read an image as base64 and return ``[text, image]`` content blocks."""
+    try:
+        raw = resolved.read_bytes()
+    except OSError as exc:
+        return f"Error: cannot read image {resolved.name!r}: {exc}"
+    size = len(raw)
+    if size > _MAX_IMAGE_BYTES:
+        return (
+            f"Error: image {resolved.name!r} is {size} bytes, exceeding the "
+            f"{_MAX_IMAGE_BYTES} byte limit. Downscale or compress it before reading."
+        )
+    data = base64.b64encode(raw).decode("ascii")
+    description = f"Image {resolved.name} ({mime}, {size} bytes)"
+    return [
+        {"type": "text", "text": description},
+        {
+            "type": "image",
+            "source": {
+                "type": "base64",
+                "media_type": mime,
+                "data": data,
+            },
+        },
+    ]
+
+
+def _read_notebook(resolved: Path) -> str:
+    """Render a Jupyter notebook's markdown/code cells (+ outputs) as text."""
+    try:
+        raw = resolved.read_text(encoding="utf-8")
+    except OSError as exc:
+        return f"Error: cannot read notebook {resolved.name!r}: {exc}"
+    try:
+        nb = json.loads(raw)
+    except (json.JSONDecodeError, ValueError) as exc:
+        return f"Error: notebook {resolved.name!r} is not valid JSON: {exc}"
+
+    cells = nb.get("cells") if isinstance(nb, dict) else None
+    if not isinstance(cells, list):
+        return f"Error: notebook {resolved.name!r} has no 'cells' array"
+
+    parts: list[str] = []
+    for index, cell in enumerate(cells, start=1):
+        if not isinstance(cell, dict):
+            continue
+        cell_type = cell.get("cell_type")
+        source = _join_source(cell.get("source"))
+        if cell_type == "markdown":
+            parts.append(f"## Markdown cell {index}\n{source}")
+        elif cell_type == "code":
+            block = f"## Code cell {index}\n{source}"
+            outputs = _render_outputs(cell.get("outputs"))
+            if outputs:
+                block += f"\n### Output\n{outputs}"
+            parts.append(block)
+        # Other cell types (e.g. raw) are skipped.
+
+    rendered = "\n\n".join(parts)
+    return _cap_document(rendered)
+
+
+def _join_source(source: Any) -> str:
+    """Notebook ``source`` is a list of lines or a single string."""
+    if isinstance(source, list):
+        return "".join(str(item) for item in source)
+    if isinstance(source, str):
+        return source
+    return ""
+
+
+def _render_outputs(outputs: Any) -> str:
+    """Extract human-readable text from a code cell's ``outputs`` array."""
+    if not isinstance(outputs, list):
+        return ""
+    rendered: list[str] = []
+    for output in outputs:
+        if not isinstance(output, dict):
+            continue
+        output_type = output.get("output_type")
+        text = ""
+        if output_type == "stream":
+            text = _join_source(output.get("text"))
+        elif output_type in ("execute_result", "display_data"):
+            data = output.get("data")
+            if isinstance(data, dict):
+                text = _join_source(data.get("text/plain"))
+        elif output_type == "error":
+            traceback = output.get("traceback")
+            if isinstance(traceback, list):
+                text = "\n".join(str(line) for line in traceback)
+        if text:
+            rendered.append(_truncate(text, _MAX_CELL_OUTPUT_CHARS))
+    return "\n".join(rendered)
+
+
+def _read_pdf(resolved: Path, pages: str | None) -> str:
+    """Extract text from a PDF. Needs the ``[pdf]`` extra (pypdf)."""
+    try:
+        from pypdf import PdfReader  # type: ignore[import-untyped]
+    except ImportError:
+        return (
+            'Error: PDF support is not installed. Run uv pip install -e ".[pdf]" '
+            "(or pip install pypdf)."
+        )
+
+    try:
+        reader = PdfReader(str(resolved))
+    except Exception as exc:  # noqa: BLE001 - pypdf raises a variety of types
+        return f"Error: cannot open PDF {resolved.name!r}: {type(exc).__name__}: {exc}"
+
+    total = len(reader.pages)
+    if total == 0:
+        return f"Error: PDF {resolved.name!r} has no pages"
+
+    selection = _parse_page_range(pages, total)
+    if isinstance(selection, str):
+        return selection  # error message
+
+    parts: list[str] = []
+    for page_no in selection:
+        try:
+            text = reader.pages[page_no].extract_text() or ""
+        except Exception as exc:  # noqa: BLE001 - extraction can fail per page
+            text = f"[Error extracting text: {type(exc).__name__}: {exc}]"
+        parts.append(f"--- Page {page_no + 1} ---\n{text}")
+
+    return _cap_document("\n\n".join(parts))
+
+
+def _parse_page_range(pages: str | None, total: int) -> list[int] | str:
+    """Parse a 1-based user page spec into a list of 0-based indices.
+
+    Accepts ``None`` (all pages), ``"3"`` (single page) and ``"1-5"`` (range).
+    A range's ``end`` past the last page is clamped, but a ``start`` past the
+    last page is an explicit error (mirroring the single-page branch) rather
+    than silently returning a different page. Returns an Error string on bad
+    input.
+    """
+    if pages is None:
+        return list(range(total))
+    spec = pages.strip()
+    if not spec:
+        return list(range(total))
+
+    if "-" in spec:
+        start_str, _, end_str = spec.partition("-")
+        try:
+            start = int(start_str)
+            end = int(end_str)
+        except ValueError:
+            return f"Error: invalid page range {pages!r} (expected e.g. '1-5' or '3')"
+        if start < 1 or end < 1 or start > end:
+            return f"Error: invalid page range {pages!r}"
+        if start > total:
+            return f"Error: page range start {start} out of range (PDF has {total} pages)"
+        start_idx = start - 1
+        end_idx = min(end, total)
+        return list(range(start_idx, end_idx))
+
+    try:
+        single = int(spec)
+    except ValueError:
+        return f"Error: invalid page range {pages!r} (expected e.g. '1-5' or '3')"
+    if single < 1:
+        return f"Error: invalid page number {pages!r}"
+    if single > total:
+        return f"Error: page {single} out of range (PDF has {total} pages)"
+    return [single - 1]
+
+
+def _truncate(text: str, max_chars: int) -> str:
+    if len(text) <= max_chars:
+        return text
+    return text[:max_chars] + _TRUNCATED_MARKER
+
+
+def _cap_document(text: str) -> str:
+    if len(text) <= _MAX_DOCUMENT_CHARS:
+        return text
+    return text[:_MAX_DOCUMENT_CHARS] + f"\n{_TRUNCATED_MARKER}"

bareagent/core/handlers/file_write.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from bareagent.core.sandbox import safe_path
+
+
+def run_write(
+    file_path: str,
+    content: str,
+    *,
+    workspace: Path,
+    diagnostics_hook: Callable[[str, Any], str | None] | None = None,
+) -> str:
+    """Write content to a workspace file, creating parent directories when needed.
+
+    ``diagnostics_hook`` (Hybrid auto-diagnostics) follows the same contract
+    as :func:`run_edit`: the handler snapshots before, performs the write,
+    then asks the hook for an appendix. Returning ``None`` from either call
+    leaves the result untouched.
+    """
+    resolved = safe_path(file_path, workspace)
+    resolved.parent.mkdir(parents=True, exist_ok=True)
+    before = diagnostics_hook(str(resolved), None) if diagnostics_hook else None
+    resolved.write_text(content, encoding="utf-8")
+    relative = resolved.relative_to(workspace.resolve(strict=False))
+    result = f"Wrote {len(content)} characters to {relative.as_posix()}"
+    if diagnostics_hook is not None:
+        appendix = diagnostics_hook(str(resolved), before)
+        if appendix:
+            result = f"{result}{appendix}"
+    return result

bareagent/core/handlers/glob_search.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from bareagent.core.handlers.search_utils import (
+    iter_search_files,
+    matches_glob_pattern,
+)
+from bareagent.core.sandbox import safe_path
+
+
+def run_glob(pattern: str, path: str = ".", *, workspace: Path) -> list[str]:
+    """Return workspace-relative paths that match a glob pattern."""
+    workspace_path = workspace.resolve(strict=False)
+    search_root = safe_path(path, workspace_path)
+
+    if search_root.is_file():
+        candidates = [search_root]
+    else:
+        candidates = list(iter_search_files(search_root))
+
+    matches: list[str] = []
+    for candidate in candidates:
+        resolved = candidate.resolve(strict=False)
+        if not resolved.is_relative_to(workspace_path):
+            continue
+        if not matches_glob_pattern(resolved, search_root, pattern):
+            continue
+        matches.append(resolved.relative_to(workspace_path).as_posix())
+    return sorted(dict.fromkeys(matches))

bareagent/core/handlers/goal.py

@@ -0,0 +1,60 @@
+"""Handler + schema for the ``goal_verdict`` tool (goal-completion evaluator).
+
+Like ``skill_create``, ``goal_verdict`` is NOT registered in the global tool set.
+It is exposed only inside the isolated evaluator ``agent_loop`` call that runs
+after each turn of a ``/goal`` loop (see ``main.py`` and ``src/core/goal.py``).
+Keeping it out of the global set means the main loop never offers it and
+sub-agents never receive it (isolation, same stance as ``skill_create`` /
+``hook_engine``).
+
+The handler is a thin shim: it parses the model-supplied fields into a
+:class:`bareagent.core.goal.Verdict` (delegating coercion to ``goal.parse_verdict``)
+and records it into a caller-provided ``sink`` list as a side effect, mirroring
+how ``skill_create`` persists via its store. The caller reads ``sink`` after the
+isolated evaluator loop returns. Returning a plain confirmation string keeps the
+evaluator loop from crashing (see ``error-handling.md``).
+"""
+
+from __future__ import annotations
+
+from bareagent.core.goal import Verdict, parse_verdict
+from bareagent.core.schema import tool_schema
+
+GOAL_VERDICT_TOOL_SCHEMA = tool_schema(
+    "goal_verdict",
+    (
+        "Report whether the goal completion condition is now fully satisfied, "
+        "judging only from the conversation. Call exactly once."
+    ),
+    {
+        "met": {
+            "type": "boolean",
+            "description": "True only if the transcript verifiably satisfies the condition.",
+        },
+        "reason": {
+            "type": "string",
+            "description": (
+                "Concrete justification. If not met, name what is still missing "
+                "and what the agent should do next."
+            ),
+        },
+    },
+    ["met", "reason"],
+)
+
+
+def run_goal_verdict(
+    *,
+    sink: list[Verdict],
+    met: object = None,
+    reason: object = None,
+) -> str:
+    """Record the evaluator's verdict into ``sink`` and confirm to the model.
+
+    ``sink`` is a one-element accumulator the caller reads after the isolated
+    evaluator loop returns. Coercion/validation lives in ``goal.parse_verdict``,
+    so this stays a thin shim that never raises.
+    """
+    verdict = parse_verdict({"met": met, "reason": reason})
+    sink.append(verdict)
+    return "Verdict recorded."

bareagent/core/handlers/grep_search.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from bareagent.core.handlers.search_utils import iter_search_files
+from bareagent.core.sandbox import safe_path
+
+MAX_MATCHES = 1000
+MAX_FILE_SIZE = 1_048_576  # 1 MB
+
+
+def run_grep(
+    pattern: str,
+    path: str = ".",
+    include: str = "",
+    *,
+    workspace: Path,
+) -> list[str]:
+    """Search for a regex pattern in workspace files."""
+    workspace_path = workspace.resolve(strict=False)
+    search_root = safe_path(path, workspace_path)
+    try:
+        regex = re.compile(pattern)
+    except re.error as exc:
+        return [f"Invalid regex pattern: {exc}"]
+
+    matches: list[str] = []
+    for file_path in iter_search_files(search_root):
+        resolved = file_path.resolve(strict=False)
+        if not resolved.is_relative_to(workspace_path):
+            continue
+
+        relative = resolved.relative_to(workspace_path)
+        if include and not relative.match(include):
+            continue
+
+        try:
+            if resolved.stat().st_size > MAX_FILE_SIZE:
+                continue
+            lines = resolved.read_text(encoding="utf-8").splitlines()
+        except (OSError, UnicodeDecodeError):
+            continue
+
+        for line_number, line in enumerate(lines, start=1):
+            if regex.search(line):
+                matches.append(f"{relative.as_posix()}:{line_number}:{line}")
+                if len(matches) >= MAX_MATCHES:
+                    break
+        if len(matches) >= MAX_MATCHES:
+            break
+    return matches

bareagent/core/handlers/memory.py

@@ -0,0 +1,71 @@
+"""Handler for the single ``memory`` tool.
+
+Thin dispatcher over :class:`bareagent.memory.persistent.MemoryManager`. It validates
+per-command required arguments and converts the manager's stdlib exceptions
+into ``Error:`` strings so the LLM can read and react to failures instead of
+crashing the agent loop (see ``.trellis/spec/backend/error-handling.md``).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from bareagent.memory.persistent import MemoryManager
+
+# Predictable, LLM-facing failures. Anything outside this set is a real bug and
+# is allowed to propagate to the loop's blanket safety net.
+_HANDLED_ERRORS = (
+    FileNotFoundError,
+    PermissionError,
+    ValueError,
+    IsADirectoryError,
+    NotADirectoryError,
+    OSError,
+)
+
+
+def run_memory(
+    *,
+    manager: MemoryManager,
+    command: str,
+    path: str | None = None,
+    file_text: str | None = None,
+    old_str: str | None = None,
+    new_str: str | None = None,
+    insert_line: int | None = None,
+    insert_text: str | None = None,
+    old_path: str | None = None,
+    new_path: str | None = None,
+    view_range: list[int] | None = None,
+) -> str:
+    cmd = (command or "").strip()
+    try:
+        if cmd == "view":
+            return manager.view(path or ".", view_range=view_range)
+        if cmd == "create":
+            if path is None or file_text is None:
+                return "Error: create requires 'path' and 'file_text'."
+            return manager.create(path, file_text)
+        if cmd == "str_replace":
+            if path is None or old_str is None or new_str is None:
+                return "Error: str_replace requires 'path', 'old_str', and 'new_str'."
+            return manager.str_replace(path, old_str, new_str)
+        if cmd == "insert":
+            if path is None or insert_line is None or insert_text is None:
+                return "Error: insert requires 'path', 'insert_line', and 'insert_text'."
+            return manager.insert(path, int(insert_line), insert_text)
+        if cmd == "delete":
+            if path is None:
+                return "Error: delete requires 'path'."
+            return manager.delete(path)
+        if cmd == "rename":
+            if old_path is None or new_path is None:
+                return "Error: rename requires 'old_path' and 'new_path'."
+            return manager.rename(old_path, new_path)
+    except _HANDLED_ERRORS as exc:
+        return f"Error: {exc}"
+    return (
+        f"Error: unknown memory command {command!r}. "
+        "Valid commands: view, create, str_replace, insert, delete, rename."
+    )

bareagent/core/handlers/plan.py

@@ -0,0 +1,106 @@
+"""Handler + schema for the ``exit_plan_mode`` tool (plan-mode workflow).
+
+Like ``skill_create``, ``exit_plan_mode`` is NOT registered in the global tool
+set (``core/tools.py``). It is injected only into the *main* REPL loop's tool
+list in ``main.py`` after the base handlers are built. Keeping it out of
+``get_tools()`` / the base handler dict means sub-agents never receive it:
+``run_subagent`` filters tools by the base schema list (which lacks it) and
+``filter_handlers`` then drops the orphaned handler. A sub-agent must never be
+able to flip the parent's permission mode.
+
+The handler is pure: it validates the plan, delegates the user interaction and
+the permission-mode flip to an injected ``approve_fn`` (wired in ``main.py``
+where the UI console and ``PermissionGuard`` live), and maps the resulting
+decision to an ``Error:``-or-instruction string the LLM reads to decide what to
+do next. This keeps ``core/handlers`` free of any dependency on ``permission`` /
+``ui`` and makes the mapping unit-testable with a fake ``approve_fn``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from bareagent.core.schema import tool_schema
+
+EXIT_PLAN_MODE_TOOL_SCHEMA = tool_schema(
+    "exit_plan_mode",
+    (
+        "Present your completed implementation plan for user approval and leave "
+        "plan mode. Call this only after researching the task with read-only "
+        "tools. On approval the permission mode switches and you continue with "
+        "the implementation; on rejection you stay in plan mode and revise."
+    ),
+    {
+        "plan": {
+            "type": "string",
+            "description": (
+                "The implementation plan as markdown: what you will change, in "
+                "what order, and any risks. Concise but complete."
+            ),
+        },
+    },
+    ["plan"],
+)
+
+
+@dataclass(frozen=True, slots=True)
+class PlanDecision:
+    """Outcome of the plan-approval interaction.
+
+    ``outcome`` is one of:
+
+    - ``"approve-default"`` -- user approved; mode flipped to DEFAULT.
+    - ``"approve-auto"`` -- user approved with auto-accept; mode flipped to AUTO.
+    - ``"reject"`` -- user rejected; ``reason`` carries optional feedback.
+    - ``"noop"`` -- called while not in plan mode (defensive; nothing happened).
+    - ``"unavailable"`` -- no interactive approval possible (non-tty); stayed in plan.
+    """
+
+    outcome: str
+    reason: str = ""
+
+
+def run_exit_plan_mode(
+    *,
+    plan: str | None = None,
+    approve_fn: Callable[[str], PlanDecision],
+) -> str:
+    if not plan or not str(plan).strip():
+        return "Error: exit_plan_mode requires a non-empty 'plan'."
+
+    decision = approve_fn(str(plan))
+
+    if decision.outcome == "approve-default":
+        return (
+            "Plan approved. Permission mode is now DEFAULT (write operations are "
+            "still confirmed individually). Proceed with the implementation."
+        )
+    if decision.outcome == "approve-auto":
+        return (
+            "Plan approved with auto-accept. Permission mode is now AUTO (safe "
+            "commands run without prompts; dangerous ones are still blocked). "
+            "Proceed with the implementation."
+        )
+    if decision.outcome == "unavailable":
+        return (
+            "Plan approval is unavailable in a non-interactive environment. Staying in plan mode."
+        )
+    if decision.outcome == "noop":
+        return (
+            "Error: exit_plan_mode is only valid in plan mode, and you are not "
+            "currently in plan mode."
+        )
+    # Reject is the safety-net default for any unexpected outcome: staying in
+    # plan mode is the conservative choice (never auto-grant write access).
+    reason = decision.reason.strip()
+    if reason:
+        return (
+            f"The user rejected the plan. Reason: {reason}\n"
+            "You are still in plan mode. Revise the plan to address this feedback "
+            "and call exit_plan_mode again."
+        )
+    return (
+        "The user rejected the plan. You are still in plan mode. Revise the plan "
+        "and call exit_plan_mode again."
+    )