scootcli 0.1.0__py3-none-any.whl

scootcli/__init__.py

@@ -0,0 +1,4 @@
+"""scoot: a tiny coding agent that goes where you point it."""
+
+__version__ = "0.1.0"
+

scootcli/__main__.py

@@ -0,0 +1,9 @@
+"""Enable ``python -m scootcli``."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())
+

scootcli/activity.py

@@ -0,0 +1,26 @@
+"""Shared 'activity' context manager: spinner + ESC-interrupt around a blocking call.
+
+Used by slash-commands (``/init``, ``/compact``) that call the model outside the agent loop. Yields a
+``cancel_event`` the caller passes to ``client.chat`` so ESC terminates it immediately.
+"""
+
+from __future__ import annotations
+
+import threading
+from contextlib import contextmanager
+
+from .keys import InterruptibleSection
+from .status import Status
+
+
+@contextmanager
+def activity(message: str):
+    cancel = threading.Event()
+    status = Status()
+    status.start(message)
+    try:
+        with InterruptibleSection(cancel):
+            yield cancel
+    finally:
+        status.stop()
+

scootcli/agent.py

@@ -0,0 +1,350 @@
+"""The agentic loop (PLAN §7).
+
+Each turn: build messages → call the model with the tool schemas → if it returns ``tool_calls``,
+approve + execute each and loop; otherwise the plain-text reply is the completion (DONE sentinel
+stripped). Bounded by ``max_steps``. ESC cancellation is honored around every blocking call.
+
+The loop runs on the *calling* thread and delegates all terminal concerns (spinner, ESC listener,
+approval prompts) to an injected ``ui`` object, so it stays decoupled and unit-testable (see
+:class:`HeadlessUI`).
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import List, Optional
+
+from . import tools
+from .approvals import Approval, Decision, needs_prompt
+from .config import Config
+from .errors import ScootError, ContextLengthError, Interrupted, ModelUnavailableError
+from .prompts import build_agent_system_prompt
+from .tools.base import ToolContext, ToolResult
+
+
+@dataclass
+class AgentOutcome:
+    status: str  # "done" | "interrupted" | "aborted" | "max_steps" | "error"
+    content: str = ""
+    error: str = ""
+    steps: int = 0
+    streamed: bool = False  # True if the final content was already printed live (streaming)
+
+
+def _strip_done(text: str) -> str:
+    """Remove a trailing ``DONE`` sentinel line from the model's final message."""
+    lines = (text or "").rstrip().splitlines()
+    while lines and lines[-1].strip() in ("DONE", ""):
+        if lines[-1].strip() == "DONE":
+            lines.pop()
+            break
+        lines.pop()
+    return "\n".join(lines).rstrip()
+
+
+def _fmt_error(exc: Exception) -> str:
+    """Format an error with its actionable hint, if any."""
+    hint = getattr(exc, "hint", "")
+    return f"{exc}" + (f" — {hint}" if hint else "")
+
+
+class HeadlessUI:
+    """A non-interactive UI for programmatic/testing use (no spinner; fixed approval decision)."""
+
+    def __init__(self, decision: Decision = Decision.APPROVE):
+        self.decision = decision
+        self.events: List[tuple] = []
+
+    @contextmanager
+    def activity(self, message: str, cancel_event: threading.Event):
+        self.events.append(("activity", message))
+        yield
+
+    def assistant(self, text: str) -> None:
+        self.events.append(("assistant", text))
+
+    def approve(self, tool, args, ctx) -> Approval:
+        self.events.append(("approve", tool.name, args))
+        return Approval(self.decision, args)
+
+    def auto_approved(self, tool, args) -> None:
+        self.events.append(("auto", tool.name, args))
+
+    def plan(self, plan) -> None:
+        self.events.append(("plan", plan))
+
+    def tool_result(self, name: str, result: ToolResult) -> None:
+        self.events.append(("tool_result", name, result.ok, result.summary))
+
+
+class Agent:
+    """Runs the agentic loop for one user turn."""
+
+    def __init__(self, config: Config, provider):
+        self.config = config
+        self.provider = provider  # a Provider (usually the ProviderPool); dispatches by provider/model
+        self._streaming = getattr(config, "stream", True)
+        tools.load_builtins()
+
+    # ── public API ───────────────────────────────────────────────────────────────
+    def run_turn(self, session, ui, cancel_event: Optional[threading.Event] = None) -> AgentOutcome:
+        cancel_event = cancel_event or threading.Event()
+        cfg = getattr(session, "config", None) or self.config
+        session.active_model = self._pick_model(session)
+        self._refresh_workspace(session, cfg)
+        steps = 0
+        compacted = False
+        while True:
+            if cancel_event.is_set():
+                return AgentOutcome("interrupted", steps=steps)
+            steps += 1
+            if steps > cfg.max_steps:
+                return AgentOutcome("max_steps", steps=steps - 1)
+
+            try:
+                result, streamed = self._model_call(session, cfg, ui, cancel_event, steps)
+            except Interrupted:
+                return AgentOutcome("interrupted", steps=steps)
+            except ModelUnavailableError as exc:
+                if self._fallback_model(session):
+                    ui.assistant(f"model unavailable — switching to {session.active_model}.")
+                    steps -= 1  # don't count the failed attempt
+                    continue
+                return AgentOutcome("error", error=_fmt_error(exc), steps=steps)
+            except ContextLengthError as exc:
+                if not compacted and session.messages:
+                    compacted = True
+                    try:
+                        from .context import compact
+                        with ui.activity("context too long — compacting…", cancel_event):
+                            compact(session, cancel_event)
+                        steps -= 1
+                        continue
+                    except ScootError:
+                        pass
+                return AgentOutcome("error", error=_fmt_error(exc), steps=steps)
+            except ScootError as exc:
+                return AgentOutcome("error", error=_fmt_error(exc), steps=steps)
+
+            session.account(result.usage)
+            session.messages.append(self._assistant_message(result))
+
+            if result.tool_calls:
+                if (result.content or "").strip() and not streamed:
+                    ui.assistant(result.content.strip())
+                signal = self._run_tools(session, result.tool_calls, ui, cancel_event, cfg)
+                if signal in ("abort", "interrupted"):
+                    status = "aborted" if signal == "abort" else "interrupted"
+                    return AgentOutcome(status, steps=steps)
+                continue
+
+            # No tool calls -> the model is done.
+            return AgentOutcome(
+                "done", content=_strip_done(result.content), steps=steps, streamed=streamed
+            )
+
+    # ── model call (streaming or buffered) ───────────────────────────────────────
+    def _model_call(self, session, cfg, ui, cancel_event, steps):
+        """Call the model, streaming tokens live when the UI supports it.
+
+        Returns ``(result, streamed)`` where ``streamed`` is True if content was already printed.
+        """
+        messages = self._messages(session, cfg)
+        hints = {"task_text": self._last_user_text(session), "needs_tools": True, "step": steps}
+        if self._streaming and hasattr(ui, "stream") and hasattr(self.provider, "chat_stream"):
+            with ui.stream(cancel_event) as streamer:
+                result = self.provider.chat_stream(
+                    messages,
+                    model=session.active_model,
+                    tools=tools.schemas(),
+                    tool_choice="auto",
+                    cancel_event=cancel_event,
+                    on_delta=streamer.delta,
+                    hints=hints,
+                )
+            return result, bool(getattr(streamer, "started", False))
+
+        with ui.activity(f"thinking… (step {steps})", cancel_event):
+            result = self.provider.chat(
+                messages,
+                model=session.active_model,
+                tools=tools.schemas(),
+                tool_choice="auto",
+                cancel_event=cancel_event,
+                hints=hints,
+            )
+        return result, False
+
+    @staticmethod
+    def _last_user_text(session) -> str:
+        for m in reversed(getattr(session, "messages", []) or []):
+            if m.get("role") == "user" and isinstance(m.get("content"), str):
+                return m["content"]
+        return ""
+
+    # ── message construction ─────────────────────────────────────────────────────
+    def _pick_model(self, session) -> str:
+        """Resolve the model for this turn. For ``auto``, use the heuristic over live models."""
+        if session.model.lower() != "auto":
+            return session.resolved_model()
+        from .models import resolve_auto
+
+        last_user = self._last_user_text(session)
+        try:
+            available = session.available_models()
+        except Exception:
+            available = []
+        bad = getattr(session, "bad_models", None) or set()
+        available = [m for m in available if m not in bad] or available
+        return resolve_auto(last_user, available, fallback=session.resolved_model())
+
+    def _fallback_model(self, session) -> bool:
+        """After a model-unavailable error, blacklist it and switch models. Returns False if stuck."""
+        bad = session.active_model
+        fallback = session.resolved_model()
+        if bad == fallback and session.model.lower() != "auto":
+            return False
+        if hasattr(session, "bad_models"):
+            session.bad_models.add(bad)
+        new = self._pick_model(session)
+        if new == bad:
+            if bad == fallback:
+                return False
+            new = fallback
+        session.active_model = new
+        return True
+
+    def _messages(self, session, cfg=None) -> List[dict]:
+        cfg = cfg or getattr(session, "config", None) or self.config
+        system = build_agent_system_prompt(
+            root=cfg.root,
+            model=session.active_model,
+            tool_list=tools.tool_list_text(),
+            workspace=getattr(session, "workspace_ctx", ""),
+        )
+        return [{"role": "system", "content": system}, *session.messages]
+
+    def _refresh_workspace(self, session, cfg) -> None:
+        """Recompute the workspace map once per turn (best-effort; stored on the session)."""
+        ctx = ""
+        if getattr(cfg, "workspace_context", True):
+            try:
+                from .workspace import workspace_context
+
+                ctx = workspace_context(cfg.root)
+            except Exception:
+                ctx = ""
+        try:
+            session.workspace_ctx = ctx
+        except Exception:
+            pass
+
+    @staticmethod
+    def _assistant_message(result) -> dict:
+        """The history entry for a model reply. ``provider_items`` (opaque items such as encrypted
+        reasoning) ride along so the adapter that produced them can replay them next call."""
+        msg = {"role": "assistant", "content": result.content or ""}
+        if result.tool_calls:
+            msg["tool_calls"] = result.tool_calls
+        raw = result.raw_message if isinstance(result.raw_message, dict) else {}
+        if raw.get("provider_items"):
+            msg["provider_items"] = raw["provider_items"]
+        return msg
+
+    @staticmethod
+    def _append_tool(session, tool_call_id: str, content: str) -> None:
+        session.messages.append(
+            {"role": "tool", "tool_call_id": tool_call_id, "content": content}
+        )
+
+    @staticmethod
+    def _parse_args(raw) -> dict:
+        if isinstance(raw, dict):
+            return raw
+        if not raw:
+            return {}
+        try:
+            parsed = json.loads(raw)
+            return parsed if isinstance(parsed, dict) else {}
+        except (json.JSONDecodeError, TypeError):
+            return {}
+
+    # ── tool execution ───────────────────────────────────────────────────────────
+    def _run_tools(self, session, tool_calls, ui, cancel_event, cfg=None) -> Optional[str]:
+        cfg = cfg or getattr(session, "config", None) or self.config
+        ctx = ToolContext(root=cfg.root, config=cfg, cancel_event=cancel_event)
+        mode = getattr(session, "approval_mode", "always")
+        # Session trust-list: tools the user chose to auto-approve for the rest of the session.
+        trusted = getattr(session, "trusted_tools", None)
+        if trusted is None:
+            trusted = set()
+            try:
+                session.trusted_tools = trusted
+            except Exception:
+                pass
+        for tc in tool_calls:
+            if cancel_event.is_set():
+                return "interrupted"
+            tc_id = tc.get("id", "")
+            fn = tc.get("function", {}) or {}
+            name = fn.get("name", "")
+            args = self._parse_args(fn.get("arguments"))
+
+            tool = tools.get(name)
+            if tool is None:
+                self._append_tool(session, tc_id, f"error: unknown tool '{name}'")
+                continue
+
+            # Approval policy: auto-approve when the mode/trust allows it, else prompt.
+            if needs_prompt(mode, tool, args, trusted) is None:
+                if not getattr(tool, "auto_approve", False):
+                    ui.auto_approved(tool, args)  # meta tools render their own output
+            else:
+                approval = ui.approve(tool, args, ctx)
+                if approval.decision == Decision.ABORT:
+                    self._append_tool(session, tc_id, "user aborted the operation")
+                    return "abort"
+                if approval.decision == Decision.SKIP:
+                    self._append_tool(
+                        session, tc_id, "user declined this action; consider another approach"
+                    )
+                    ui.tool_result(name, ToolResult(ok=False, summary="skipped"))
+                    continue
+                if approval.decision == Decision.APPROVE_TOOL:
+                    trusted.add(name)
+                    ui.assistant(f"trusting {name} for the rest of this session.")
+                elif approval.decision == Decision.APPROVE_SESSION:
+                    session.approval_mode = mode = "yolo"
+                    ui.assistant("auto-approving all tool calls for this session (yolo).")
+                args = approval.args
+
+            try:
+                with ui.activity(f"running {name}…", cancel_event):
+                    result = tool.run(args, ctx)
+            except Interrupted:
+                return "interrupted"
+            except Exception as exc:  # a tool must never take down the loop
+                result = ToolResult.fail(f"tool crashed: {exc}")
+
+            self._handle_result(session, name, result, ui)
+            payload = result.content if result.ok else f"ERROR: {result.error}"
+            self._append_tool(session, tc_id, payload or "(no output)")
+        return None
+
+    @staticmethod
+    def _handle_result(session, name: str, result: ToolResult, ui) -> None:
+        """Surface a tool result: render a plan update specially, else the generic result line."""
+        plan = result.meta.get("plan") if (result.ok and isinstance(result.meta, dict)) else None
+        if plan is not None:
+            try:
+                session.plan = plan
+            except Exception:
+                pass
+            if hasattr(ui, "plan"):
+                ui.plan(plan)
+                return
+        ui.tool_result(name, result)
+

scootcli/approvals.py

@@ -0,0 +1,167 @@
+"""Human-in-the-loop approvals (PLAN §9).
+
+Default policy is ``always``: every tool call is shown and must be approved. The prompt renders the
+tool name + arguments and, for writes/shell, a rich preview (diff or command). Inline single-key
+controls:
+
+    [a] approve once   [t] trust this tool for the session   [A] approve all this session (yolo)
+    [e] edit arguments   [s] skip (tell the model no)   [q] abort the agent
+
+``[t]`` and ``[A]`` fight approval fatigue on read-heavy tasks; the shell denylist still re-confirms
+catastrophic commands even after ``[A]``.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from enum import Enum
+
+from .keys import read_key
+from .rendering import color, eprint
+from .tools.base import Tool, ToolContext
+
+
+class Decision(Enum):
+    APPROVE = "approve"
+    APPROVE_TOOL = "approve_tool"        # trust this tool for the rest of the session
+    APPROVE_SESSION = "approve_session"  # approve everything for the rest of the session (yolo)
+    SKIP = "skip"
+    ABORT = "abort"
+
+
+@dataclass
+class Approval:
+    decision: Decision
+    args: dict  # possibly edited by the user
+
+
+# ── Approval modes (increasing autonomy) ───────────────────────────────────────
+#   always     — prompt for every tool call
+#   auto-read  — auto-approve read-only tools; prompt writes & shell
+#   auto-edits — auto-approve reads AND file writes/edits; prompt shell only
+#   yolo       — auto-approve everything (denylisted shell commands still confirmed)
+MODES = ("always", "auto-read", "auto-edits", "yolo")
+
+# Catastrophic shell commands that are ALWAYS confirmed, even in yolo mode.
+_DENYLIST = [
+    (re.compile(r"\brm\s+-[a-z]*r[a-z]*f|\brm\s+-[a-z]*f[a-z]*r", re.I), "recursive force delete"),
+    (re.compile(r":\(\)\s*\{.*\|.*&\s*\}\s*;", re.S), "fork bomb"),
+    (re.compile(r"\bgit\s+push\b", re.I), "git push"),
+    (re.compile(r"\bsudo\b", re.I), "sudo"),
+    (re.compile(r"\b(shutdown|reboot|halt|poweroff)\b", re.I), "power/shutdown"),
+    (re.compile(r"\bmkfs\b|\bdd\s+.*of=/dev/", re.I), "disk/format command"),
+    (re.compile(r"\b(curl|wget|nc|ncat|scp|sftp)\b", re.I), "outbound network command"),
+    (re.compile(r"\bchmod\s+-[a-z]*r|\bchown\s+-[a-z]*r", re.I), "recursive permission change"),
+    (re.compile(r">\s*/dev/(sd|nvme|disk)", re.I), "write to raw disk"),
+]
+
+
+def denylisted_reason(command: str):
+    """Return a reason string if the shell command matches the always-confirm denylist, else None."""
+    for pattern, reason in _DENYLIST:
+        if pattern.search(command or ""):
+            return reason
+    return None
+
+
+def needs_prompt(mode: str, tool: Tool, args: dict, trusted=()) -> "str | None":
+    """Decide whether a tool call must be prompted.
+
+    Returns ``None`` if it may be auto-approved, or a short reason string if a prompt is required.
+    ``trusted`` is the set of tool names the user chose to auto-approve for this session.
+    Denylisted shell commands are ALWAYS confirmed, regardless of mode or trust.
+    """
+    if tool.name == "run_shell":
+        reason = denylisted_reason(args.get("command", ""))
+        if reason:
+            return f"blocked command ({reason})"
+    if getattr(tool, "auto_approve", False):
+        return None  # side-effect-free meta tools (e.g. update_plan) never prompt
+    if mode == "yolo":
+        return None
+    if tool.name in (trusted or ()):
+        return None
+    if mode == "auto-read":
+        return None if tool.risk == "read" else "write/shell action"
+    if mode == "auto-edits":
+        return None if tool.risk in ("read", "write") else "shell action"
+    return "approval required"  # always
+
+
+_RISK_COLOR = {"read": "cyan", "write": "yellow", "shell": "red"}
+
+
+def _render(tool: Tool, args: dict, ctx: ToolContext) -> None:
+    dot = color("●", _RISK_COLOR.get(tool.risk, "cyan"))
+    print(f"{dot} {color(tool.name, 'bold')} {color(json.dumps(args, ensure_ascii=False), 'gray')}")
+    try:
+        preview = tool.preview(args, ctx)
+    except Exception as exc:  # a preview must never crash the loop
+        preview = color(f"(preview unavailable: {exc})", "gray")
+    if preview:
+        for line in preview.splitlines():
+            print("  " + line)
+
+
+def _edit_args(args: dict) -> dict:
+    """Let the user type replacement JSON for the tool arguments."""
+    print(color("  current args: ", "gray") + json.dumps(args, ensure_ascii=False))
+    print(color("  enter new JSON (blank to keep): ", "gray"), end="", flush=True)
+    try:
+        raw = input()
+    except (EOFError, KeyboardInterrupt):
+        return args
+    raw = raw.strip()
+    if not raw:
+        return args
+    try:
+        new = json.loads(raw)
+        if isinstance(new, dict):
+            return new
+        eprint(color("  (ignored: not a JSON object)", "yellow"))
+    except json.JSONDecodeError as exc:
+        eprint(color(f"  (ignored: invalid JSON: {exc})", "yellow"))
+    return args
+
+
+def request_approval(tool: Tool, args: dict, ctx: ToolContext) -> Approval:
+    """Show the pending tool call and read the user's decision (with optional arg editing)."""
+    while True:
+        _render(tool, args, ctx)
+        print(
+            "  "
+            + color("approve", "green")
+            + " [a]  "
+            + color(f"trust {tool.name}", "green")
+            + " [t]  "
+            + color("all-session", "green")
+            + " [A]  "
+            + color("edit", "cyan")
+            + " [e]  "
+            + color("skip", "yellow")
+            + " [s]  "
+            + color("quit", "red")
+            + " [q] › ",
+            end="",
+            flush=True,
+        )
+        key = read_key()
+        print(key)  # echo the choice for a clean transcript
+
+        if key in ("a", "y", "\r", "\n", ""):
+            return Approval(Decision.APPROVE, args)
+        if key == "t":
+            return Approval(Decision.APPROVE_TOOL, args)
+        if key == "A":
+            return Approval(Decision.APPROVE_SESSION, args)
+        if key == "e":
+            args = _edit_args(args)
+            continue
+        if key == "s":
+            return Approval(Decision.SKIP, args)
+        if key in ("q", "\x1b"):
+            return Approval(Decision.ABORT, args)
+        # Unknown key: re-prompt.
+

scootcli/auth.py

@@ -0,0 +1,59 @@
+"""Where API keys come from, per provider.
+
+Order: the provider's environment variables (the vendor's standard names, ``OPENAI_API_KEY`` and so
+on, which a ``.env`` may have supplied), then scoot's own saved credentials (``scoot auth set``).
+Providers that need no key (a local Ollama) are always considered configured.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import List, Optional
+
+from . import credentials
+from .providers.base import ProviderSpec
+
+
+def api_key_for(spec: ProviderSpec) -> Optional[str]:
+    for env in spec.key_env:
+        value = (os.environ.get(env) or "").strip()
+        if value:
+            return value
+    return credentials.load_key(spec.name)
+
+
+def key_source(spec: ProviderSpec) -> Optional[str]:
+    """``"env:OPENAI_API_KEY"``, ``"saved"``, or ``None`` when no key is available."""
+    for env in spec.key_env:
+        if (os.environ.get(env) or "").strip():
+            return f"env:{env}"
+    if credentials.load_key(spec.name):
+        return "saved"
+    return None
+
+
+def is_configured(spec: ProviderSpec) -> bool:
+    return (not spec.key_required) or api_key_for(spec) is not None
+
+
+def status_rows(config) -> List[dict]:
+    """One row per registered provider: name, key source, whether a key is required, default flag."""
+    from .providers import registry
+
+    default = registry.default_provider_name(config)
+    rows = []
+    for spec in registry.all_specs():
+        rows.append({
+            "name": spec.name,
+            "source": key_source(spec),
+            "required": spec.key_required,
+            "configured": is_configured(spec),
+            "default": spec.name == default,
+            "base_url": registry.base_url_for(spec),
+        })
+    return rows
+
+
+def missing_key_hint(spec: ProviderSpec) -> str:
+    env = spec.key_env[0] if spec.key_env else f"{spec.name.upper()}_API_KEY"
+    return f"set {env} (in the environment or ~/.config/scoot/.env) or run `scoot auth set {spec.name}`"