scootcli 0.1.0__py3-none-any.whl

scootcli/sessions.py

@@ -0,0 +1,186 @@
+"""Session persistence: auto-save each turn, resume with ``--continue`` / ``--resume`` (PLAN §14).
+
+Stdlib-only and offline-friendly. Each interactive session is auto-saved after every turn to
+``~/.local/state/scoot/sessions/<id>.json`` (owner-only, ``0600``), keyed by workspace root so
+``--continue`` can find the most recent conversation for the directory you're in. Token-like strings
+are redacted before writing (defense in depth); only the most recent :data:`SESSION_RETENTION`
+sessions are kept.
+
+The state directory can be overridden with ``SCOOT_STATE_DIR`` (used by tests).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional
+
+from .config import SESSION_RETENTION, STATE_DIR
+from .rendering import redact
+
+_VERSION = 1
+
+
+def _sessions_dir() -> Path:
+    override = os.environ.get("SCOOT_STATE_DIR")
+    base = Path(override).expanduser() if override else STATE_DIR
+    return base / "sessions"
+
+
+def new_session_id() -> str:
+    """A sortable, unique id: ``YYYYmmdd-HHMMSS-<rand>``."""
+    return time.strftime("%Y%m%d-%H%M%S") + "-" + os.urandom(2).hex()
+
+
+def _redact_messages(messages: List[dict]) -> List[dict]:
+    """Copy messages, masking token-like substrings in string content fields."""
+    cleaned: List[dict] = []
+    for msg in messages:
+        m = dict(msg)
+        content = m.get("content")
+        if isinstance(content, str):
+            m["content"] = redact(content)
+        cleaned.append(m)
+    return cleaned
+
+
+@dataclass
+class SessionRecord:
+    """A persisted conversation + the session settings needed to resume it."""
+
+    id: str
+    root: str
+    created: float
+    updated: float
+    model: str
+    active_model: str
+    approval_mode: str
+    total_prompt: int = 0
+    total_completion: int = 0
+    messages: List[dict] = field(default_factory=list)
+
+    @property
+    def turns(self) -> int:
+        return sum(1 for m in self.messages if m.get("role") == "user")
+
+    def first_prompt(self) -> str:
+        for m in self.messages:
+            if m.get("role") == "user" and isinstance(m.get("content"), str):
+                text = m["content"].strip().replace("\n", " ")
+                return (text[:57] + "…") if len(text) > 58 else text
+        return "(no prompt yet)"
+
+    def to_dict(self) -> dict:
+        return {
+            "version": _VERSION,
+            "id": self.id,
+            "root": self.root,
+            "created": self.created,
+            "updated": self.updated,
+            "model": self.model,
+            "active_model": self.active_model,
+            "approval_mode": self.approval_mode,
+            "total_prompt": self.total_prompt,
+            "total_completion": self.total_completion,
+            "messages": self.messages,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "SessionRecord":
+        return cls(
+            id=data["id"],
+            root=data.get("root", ""),
+            created=data.get("created", 0.0),
+            updated=data.get("updated", 0.0),
+            model=data.get("model", "auto"),
+            active_model=data.get("active_model", ""),
+            approval_mode=data.get("approval_mode", "always"),
+            total_prompt=int(data.get("total_prompt", 0) or 0),
+            total_completion=int(data.get("total_completion", 0) or 0),
+            messages=data.get("messages", []),
+        )
+
+
+def save(record: SessionRecord) -> Optional[Path]:
+    """Persist ``record`` (owner-only), prune old sessions, and return the path (best-effort)."""
+    record.updated = time.time()
+    payload = record.to_dict()
+    payload["messages"] = _redact_messages(record.messages)
+
+    directory = _sessions_dir()
+    try:
+        directory.mkdir(parents=True, exist_ok=True)
+        try:
+            os.chmod(directory.parent, 0o700)
+            os.chmod(directory, 0o700)
+        except OSError:
+            pass
+        path = directory / f"{record.id}.json"
+        tmp = directory / f".{record.id}.tmp"
+        fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, "w") as fh:
+            json.dump(payload, fh)
+        os.replace(tmp, path)  # atomic
+        _prune()
+        return path
+    except OSError:
+        return None  # persistence must never break the REPL
+
+
+def load(session_id: str) -> Optional[SessionRecord]:
+    try:
+        data = json.loads((_sessions_dir() / f"{session_id}.json").read_text())
+        return SessionRecord.from_dict(data)
+    except (OSError, json.JSONDecodeError, KeyError):
+        return None
+
+
+def list_sessions(root: Optional[str] = None) -> List[SessionRecord]:
+    """Return saved sessions (optionally filtered to ``root``), newest first."""
+    directory = _sessions_dir()
+    records: List[SessionRecord] = []
+    try:
+        files = list(directory.glob("*.json"))
+    except OSError:
+        return []
+    for f in files:
+        try:
+            rec = SessionRecord.from_dict(json.loads(f.read_text()))
+        except (OSError, json.JSONDecodeError, KeyError):
+            continue
+        if root is None or rec.root == str(root):
+            records.append(rec)
+    records.sort(key=lambda r: r.updated, reverse=True)
+    return records
+
+
+def latest_for_root(root: str) -> Optional[SessionRecord]:
+    sessions = list_sessions(str(root))
+    return sessions[0] if sessions else None
+
+
+def delete(session_id: str) -> bool:
+    try:
+        (_sessions_dir() / f"{session_id}.json").unlink()
+        return True
+    except (FileNotFoundError, OSError):
+        return False
+
+
+def delete_all(root: Optional[str] = None) -> int:
+    count = 0
+    for rec in list_sessions(root):
+        if delete(rec.id):
+            count += 1
+    return count
+
+
+def _prune() -> None:
+    """Keep only the most recent :data:`SESSION_RETENTION` sessions (across all roots)."""
+    everything = list_sessions()
+    for rec in everything[SESSION_RETENTION:]:
+        delete(rec.id)
+

scootcli/status.py

@@ -0,0 +1,71 @@
+"""Live status region: a single-line spinner + activity message (PLAN §6, §10).
+
+Stdlib only — uses carriage-return redraws and ANSI. Runs in its own thread so the message keeps
+animating while the model call / tool runs. Auto-disables when stdout is not a TTY.
+"""
+
+from __future__ import annotations
+
+import sys
+import threading
+import time
+
+from .rendering import color
+
+_FRAMES = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+_CLEAR_LINE = "\r\033[K"
+
+
+class Status:
+    """A threaded spinner with an updatable message and a persistent step hint."""
+
+    def __init__(self, enabled: bool = True):
+        self.enabled = enabled and sys.stdout.isatty()
+        self._message = ""
+        self._hint = ""
+        self._thread = None
+        self._stop = threading.Event()
+        self._lock = threading.Lock()
+
+    def start(self, message: str = "thinking…", hint: str = "esc to stop") -> None:
+        self._message = message
+        self._hint = hint
+        if not self.enabled:
+            return
+        self._stop.clear()
+        self._thread = threading.Thread(target=self._spin, daemon=True)
+        self._thread.start()
+
+    def update(self, message: str, hint: str = None) -> None:
+        with self._lock:
+            self._message = message
+            if hint is not None:
+                self._hint = hint
+
+    def _spin(self) -> None:
+        i = 0
+        while not self._stop.is_set():
+            with self._lock:
+                message, hint = self._message, self._hint
+            frame = color(_FRAMES[i % len(_FRAMES)], "cyan")
+            tail = color(f" · {hint}", "gray") if hint else ""
+            sys.stdout.write(f"{_CLEAR_LINE}  {frame} {message}{tail}")
+            sys.stdout.flush()
+            i += 1
+            time.sleep(0.08)
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(timeout=0.3)
+            self._thread = None
+        if self.enabled:
+            sys.stdout.write(_CLEAR_LINE)
+            sys.stdout.flush()
+
+    def line(self, text: str) -> None:
+        """Print a permanent line, clearing the spinner first so it doesn't get mangled."""
+        if self.enabled:
+            sys.stdout.write(_CLEAR_LINE)
+        print(text)
+

scootcli/tools/__init__.py

@@ -0,0 +1,68 @@
+"""Tool registry. Drop a new module in this package and call :func:`register` to add a tool.
+
+The registry is the single source of truth: it feeds both the runtime ``tools`` schema sent to the
+API and the ``{{tool_list}}`` rendered into the system prompt (PLAN §2, §8).
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+from .base import Tool, ToolContext, ToolError, ToolResult
+
+__all__ = [
+    "Tool",
+    "ToolContext",
+    "ToolResult",
+    "ToolError",
+    "register",
+    "get",
+    "all_tools",
+    "schemas",
+    "tool_list_text",
+    "load_builtins",
+]
+
+_REGISTRY: Dict[str, Tool] = {}
+
+
+def register(tool: Tool) -> None:
+    _REGISTRY[tool.name] = tool
+
+
+def get(name: str) -> Optional[Tool]:
+    return _REGISTRY.get(name)
+
+
+def all_tools() -> Dict[str, Tool]:
+    return dict(sorted(_REGISTRY.items()))
+
+
+def schemas() -> List[dict]:
+    """Return the OpenAI-style tool schemas for the request ``tools`` param."""
+    return [t.schema() for t in all_tools().values()]
+
+
+def tool_list_text() -> str:
+    """One-line-per-tool summary for the system prompt ``{{tool_list}}``."""
+    return "\n".join(f"- {t.name}: {t.description}" for t in all_tools().values())
+
+
+_loaded = False
+
+
+def load_builtins() -> None:
+    """Import the built-in tool modules so they self-register (idempotent)."""
+    global _loaded
+    if _loaded:
+        return
+    from . import read_file  # noqa: F401
+    from . import list_dir  # noqa: F401
+    from . import search  # noqa: F401
+    from . import write_file  # noqa: F401
+    from . import edit_file  # noqa: F401
+    from . import run_shell  # noqa: F401
+    from . import update_plan  # noqa: F401
+
+    _loaded = True
+

scootcli/tools/base.py

@@ -0,0 +1,152 @@
+"""Tool foundation: interfaces, sandboxing, truncation, and an interruptible subprocess helper.
+
+Each tool is a small object exposing a JSON schema (for the API ``tools`` param) plus a ``run``
+handler. Tools are sandboxed to the workspace root and return a structured :class:`ToolResult` so the
+agent loop can feed errors back to the model instead of crashing (PLAN §8).
+"""
+
+from __future__ import annotations
+
+import subprocess
+import threading
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+from ..errors import ScootError, Interrupted
+
+# ── Limits (keep tool output and reads bounded) ────────────────────────────────
+MAX_READ_BYTES = 200 * 1024        # 200 KB per read_file
+MAX_OUTPUT_CHARS = 16_000          # truncate tool output fed back to the model
+MAX_OUTPUT_LINES = 400
+DEFAULT_SHELL_TIMEOUT = 60
+
+
+class ToolError(ScootError):
+    """A tool failed in a way worth surfacing (returned as ToolResult, not raised to the user)."""
+
+
+class PathEscapeError(ToolError):
+    """A path resolved outside the workspace root."""
+
+
+@dataclass
+class ToolContext:
+    """Ambient info passed to every tool invocation."""
+
+    root: Path
+    config: Any = None
+    cancel_event: Optional[threading.Event] = None
+
+
+@dataclass
+class ToolResult:
+    """Structured result of a tool call."""
+
+    ok: bool
+    content: str = ""          # text fed back to the model
+    error: str = ""            # populated when ok is False
+    summary: str = ""          # short human line for the status region, e.g. "42 lines"
+    meta: dict = field(default_factory=dict)
+
+    @classmethod
+    def fail(cls, error: str) -> "ToolResult":
+        return cls(ok=False, error=error, summary=error)
+
+
+class Tool:
+    """Base class for tools. Subclasses set ``name``/``description``/``parameters`` and impl ``run``."""
+
+    name: str = ""
+    description: str = ""
+    parameters: dict = {"type": "object", "properties": {}}
+    risk: str = "read"  # "read" | "write" | "shell" — drives the approval UI emphasis
+    auto_approve: bool = False  # meta tools with no side effects (e.g. update_plan) skip approval
+
+    def run(self, args: dict, ctx: ToolContext) -> ToolResult:  # pragma: no cover - abstract
+        raise NotImplementedError
+
+    def preview(self, args: dict, ctx: ToolContext) -> Optional[str]:
+        """Optional rich preview shown at approval time (e.g. a diff). ``None`` = args-only."""
+        return None
+
+    def schema(self) -> dict:
+        """OpenAI-style function schema for the ``tools`` request param."""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+
+# ── Sandboxing ─────────────────────────────────────────────────────────────────
+def safe_path(root: Path, raw: str) -> Path:
+    """Resolve ``raw`` against ``root`` and ensure it stays inside it. Raises PathEscapeError."""
+    if raw is None:
+        raise ToolError("missing 'path'")
+    root = root.resolve()
+    p = Path(raw)
+    if not p.is_absolute():
+        p = root / p
+    p = p.resolve()
+    try:
+        p.relative_to(root)
+    except ValueError:
+        raise PathEscapeError(f"path escapes workspace root: {raw}")
+    return p
+
+
+# ── Truncation ─────────────────────────────────────────────────────────────────
+def truncate(text: str, max_chars: int = MAX_OUTPUT_CHARS, max_lines: int = MAX_OUTPUT_LINES) -> str:
+    """Bound text by lines and chars, appending a clear truncation notice when cut."""
+    lines = text.splitlines()
+    cut = False
+    if len(lines) > max_lines:
+        lines = lines[:max_lines]
+        cut = True
+    out = "\n".join(lines)
+    if len(out) > max_chars:
+        out = out[:max_chars]
+        cut = True
+    if cut:
+        out += "\n… [output truncated]"
+    return out
+
+
+# ── Interruptible subprocess (shared by run_shell + ripgrep search) ────────────
+def run_subprocess(
+    cmd: list,
+    cwd: Path,
+    cancel_event: Optional[threading.Event] = None,
+    timeout: int = DEFAULT_SHELL_TIMEOUT,
+) -> "tuple[int, str, str]":
+    """Run ``cmd`` returning ``(returncode, stdout, stderr)``.
+
+    Honors ``cancel_event`` (ESC) by terminating the process, and enforces ``timeout``.
+    """
+    import time
+
+    proc = subprocess.Popen(
+        cmd, cwd=str(cwd), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True
+    )
+    deadline = time.time() + timeout
+    while True:
+        try:
+            stdout, stderr = proc.communicate(timeout=0.1)
+            return proc.returncode, stdout, stderr
+        except subprocess.TimeoutExpired:
+            if cancel_event is not None and cancel_event.is_set():
+                proc.terminate()
+                try:
+                    proc.communicate(timeout=2)
+                except subprocess.TimeoutExpired:
+                    proc.kill()
+                raise Interrupted("tool cancelled by user")
+            if time.time() > deadline:
+                proc.kill()
+                proc.communicate()
+                raise ToolError(f"command timed out after {timeout}s")
+

scootcli/tools/edit_file.py

@@ -0,0 +1,72 @@
+"""edit_file — surgical unique-match replacement in an existing file (with diff preview)."""
+
+from __future__ import annotations
+
+from ..rendering import diff_stats, unified_diff
+from . import register
+from .base import Tool, ToolContext, ToolError, ToolResult, safe_path
+
+
+class EditFile(Tool):
+    name = "edit_file"
+    description = (
+        "Replace an exact, unique snippet in an existing file. 'old_string' must occur exactly once."
+    )
+    risk = "write"
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "File path relative to the workspace root."},
+            "old_string": {"type": "string", "description": "Exact text to replace (must be unique)."},
+            "new_string": {"type": "string", "description": "Replacement text."},
+        },
+        "required": ["path", "old_string", "new_string"],
+    }
+
+    def _compute(self, args, ctx):
+        """Return (path, old_text, new_text). Raises ToolError on any problem."""
+        path = safe_path(ctx.root, args.get("path"))
+        if not path.exists() or not path.is_file():
+            raise ToolError(f"no such file: {args.get('path')}")
+        old_string = args.get("old_string")
+        new_string = args.get("new_string")
+        if old_string is None or new_string is None:
+            raise ToolError("both 'old_string' and 'new_string' are required")
+        old_text = path.read_text("utf-8", "replace")
+        occurrences = old_text.count(old_string)
+        if occurrences == 0:
+            raise ToolError("old_string not found in file")
+        if occurrences > 1:
+            raise ToolError(f"old_string is not unique ({occurrences} matches); add more context")
+        new_text = old_text.replace(old_string, new_string, 1)
+        return path, old_text, new_text
+
+    def preview(self, args: dict, ctx: ToolContext):
+        try:
+            _, old_text, new_text = self._compute(args, ctx)
+        except ToolError as exc:
+            return str(exc)
+        rel = args.get("path")
+        added, removed = diff_stats(old_text, new_text)
+        return f"edit {rel}  (+{added} -{removed})\n" + unified_diff(old_text, new_text, rel)
+
+    def run(self, args: dict, ctx: ToolContext) -> ToolResult:
+        try:
+            path, old_text, new_text = self._compute(args, ctx)
+        except ToolError as exc:
+            return ToolResult.fail(str(exc))
+        try:
+            path.write_text(new_text, "utf-8")
+        except OSError as exc:
+            return ToolResult.fail(f"write failed: {exc}")
+        added, removed = diff_stats(old_text, new_text)
+        return ToolResult(
+            ok=True,
+            content=f"edited {args.get('path')} (+{added} -{removed})",
+            summary=f"{args.get('path')} +{added} -{removed}",
+            meta={"added": added, "removed": removed},
+        )
+
+
+register(EditFile())
+

scootcli/tools/list_dir.py

@@ -0,0 +1,47 @@
+"""list_dir — list a directory's contents, sandboxed to the workspace root."""
+
+from __future__ import annotations
+
+from . import register
+from .base import Tool, ToolContext, ToolError, ToolResult, safe_path, truncate
+
+_HIDDEN = {".git", ".hg", ".svn", "__pycache__", ".mypy_cache", ".pytest_cache", "node_modules"}
+_MAX_ENTRIES = 300
+
+
+class ListDir(Tool):
+    name = "list_dir"
+    description = "List the entries of a directory within the workspace (directories end with '/')."
+    risk = "read"
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "Directory path (default: workspace root)."},
+        },
+    }
+
+    def run(self, args: dict, ctx: ToolContext) -> ToolResult:
+        raw = args.get("path") or "."
+        try:
+            path = safe_path(ctx.root, raw)
+        except ToolError as exc:
+            return ToolResult.fail(str(exc))
+        if not path.exists():
+            return ToolResult.fail(f"no such directory: {raw}")
+        if not path.is_dir():
+            return ToolResult.fail(f"not a directory: {raw}")
+
+        entries = []
+        for child in sorted(path.iterdir(), key=lambda c: (c.is_file(), c.name.lower())):
+            if child.name in _HIDDEN:
+                continue
+            entries.append(child.name + ("/" if child.is_dir() else ""))
+
+        shown = entries[:_MAX_ENTRIES]
+        note = "" if len(entries) <= _MAX_ENTRIES else f"\n… [{len(entries) - _MAX_ENTRIES} more]"
+        content = truncate("\n".join(shown)) + note
+        return ToolResult(ok=True, content=content or "(empty)", summary=f"{len(entries)} entries")
+
+
+register(ListDir())
+

scootcli/tools/read_file.py

@@ -0,0 +1,56 @@
+"""read_file — read a text file (optionally a line range), sandboxed to the workspace root."""
+
+from __future__ import annotations
+
+from . import register
+from .base import MAX_READ_BYTES, Tool, ToolContext, ToolError, ToolResult, safe_path, truncate
+
+
+class ReadFile(Tool):
+    name = "read_file"
+    description = (
+        "Read a UTF-8 text file within the workspace, optionally a line range. "
+        "Returns line-numbered content."
+    )
+    risk = "read"
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "File path relative to the workspace root."},
+            "start": {"type": "integer", "description": "1-based first line (optional)."},
+            "end": {"type": "integer", "description": "1-based last line, inclusive (optional)."},
+        },
+        "required": ["path"],
+    }
+
+    def run(self, args: dict, ctx: ToolContext) -> ToolResult:
+        try:
+            path = safe_path(ctx.root, args.get("path"))
+        except ToolError as exc:
+            return ToolResult.fail(str(exc))
+        if not path.exists():
+            return ToolResult.fail(f"no such file: {args.get('path')}")
+        if path.is_dir():
+            return ToolResult.fail(f"is a directory: {args.get('path')}")
+
+        data = path.read_bytes()
+        note = ""
+        if len(data) > MAX_READ_BYTES:
+            data = data[:MAX_READ_BYTES]
+            note = " [file truncated to 200 KB]"
+        lines = data.decode("utf-8", "replace").splitlines()
+
+        total = len(lines)
+        start = max(1, int(args.get("start") or 1))
+        end = int(args.get("end") or total)
+        end = min(end, total)
+        selected = lines[start - 1 : end]
+
+        width = len(str(end))
+        numbered = "\n".join(f"{i:>{width}} | {line}" for i, line in enumerate(selected, start))
+        summary = f"{len(selected)} lines" + (f" ({start}-{end} of {total})" if selected else "")
+        return ToolResult(ok=True, content=truncate(numbered) + note, summary=summary)
+
+
+register(ReadFile())
+