llmcode-cli 1.0.0__py3-none-any.whl

llm_code/runtime/sandbox.py

@@ -0,0 +1,116 @@
+"""SandboxDetector — detect container/sandbox environments and restrict paths."""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def _has_dockerenv() -> bool:
+    """Return True if the Docker sentinel file exists."""
+    return Path("/.dockerenv").exists()
+
+
+def _cgroup_indicates_container() -> bool:
+    """Return True if /proc/1/cgroup suggests a container runtime."""
+    cgroup_path = Path("/proc/1/cgroup")
+    if not cgroup_path.exists():
+        return False
+    try:
+        content = cgroup_path.read_text(errors="replace")
+        container_markers = ("docker", "kubepods", "containerd", "lxc", "/ecs/")
+        return any(marker in content for marker in container_markers)
+    except OSError:
+        return False
+
+
+def _detect_sandbox_type() -> str:
+    """Return a string describing the detected sandbox type, or 'none'."""
+    if _has_dockerenv():
+        return "docker"
+    if _cgroup_indicates_container():
+        # Try to narrow down further
+        cgroup_path = Path("/proc/1/cgroup")
+        try:
+            content = cgroup_path.read_text(errors="replace")
+            if "kubepods" in content:
+                return "kubernetes"
+            if "containerd" in content:
+                return "containerd"
+            if "lxc" in content:
+                return "lxc"
+            if "/ecs/" in content:
+                return "ecs"
+        except OSError:
+            pass
+        return "container"
+    return "none"
+
+
+def is_sandboxed() -> bool:
+    """Return True if the process appears to be running inside a container/sandbox."""
+    return _detect_sandbox_type() != "none"
+
+
+def get_sandbox_info() -> dict:
+    """Return a dict describing the current sandbox environment.
+
+    Keys
+    ----
+    sandboxed : bool
+        Whether a sandbox was detected.
+    type : str
+        One of ``"docker"``, ``"kubernetes"``, ``"containerd"``, ``"lxc"``,
+        ``"ecs"``, ``"container"``, or ``"none"``.
+    restrictions : list[str]
+        Human-readable descriptions of active restrictions.
+    """
+    sandbox_type = _detect_sandbox_type()
+    sandboxed = sandbox_type != "none"
+
+    restrictions: list[str] = []
+    if sandboxed:
+        restrictions = [
+            "Network access may be restricted",
+            "Host filesystem is not directly accessible",
+            "Privileged operations are not permitted",
+        ]
+
+    return {
+        "sandboxed": sandboxed,
+        "type": sandbox_type,
+        "restrictions": restrictions,
+    }
+
+
+def restrict_paths(base_dir: Path) -> list[Path]:
+    """Return a list of absolute paths the agent should NOT access outside *base_dir*.
+
+    These paths represent sensitive locations on the host filesystem.
+    """
+    home = Path.home()
+    sensitive: list[Path] = [
+        home / ".ssh",
+        home / ".aws",
+        home / ".config" / "gcloud",
+        home / ".gnupg",
+        home / ".netrc",
+        home / ".pgpass",
+        Path("/etc/passwd"),
+        Path("/etc/shadow"),
+        Path("/etc/sudoers"),
+        Path("/root"),
+        Path("/var/run/secrets"),  # Kubernetes service-account tokens
+    ]
+    # Only return paths that are NOT inside base_dir
+    try:
+        base_resolved = base_dir.resolve()
+    except Exception:
+        base_resolved = base_dir
+
+    result: list[Path] = []
+    for p in sensitive:
+        try:
+            p.resolve().relative_to(base_resolved)
+            # The path IS inside base_dir — don't add to restrictions
+        except ValueError:
+            result.append(p)
+    return result

llm_code/runtime/session.py

@@ -0,0 +1,268 @@
+"""Session management: immutable Session dataclass, SessionManager for persistence."""
+from __future__ import annotations
+
+import dataclasses
+import json
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+from llm_code.api.types import (
+    ContentBlock,
+    ImageBlock,
+    Message,
+    TextBlock,
+    TokenUsage,
+    ToolResultBlock,
+    ToolUseBlock,
+)
+
+
+# ---------------------------------------------------------------------------
+# Serialization helpers
+# ---------------------------------------------------------------------------
+
+def _block_to_dict(block: ContentBlock) -> dict:
+    if isinstance(block, TextBlock):
+        return {"type": "text", "text": block.text}
+    if isinstance(block, ToolUseBlock):
+        return {"type": "tool_use", "id": block.id, "name": block.name, "input": block.input}
+    if isinstance(block, ToolResultBlock):
+        return {
+            "type": "tool_result",
+            "tool_use_id": block.tool_use_id,
+            "content": block.content,
+            "is_error": block.is_error,
+        }
+    if isinstance(block, ImageBlock):
+        return {"type": "image", "media_type": block.media_type, "data": block.data}
+    raise ValueError(f"Unknown block type: {type(block)}")
+
+
+def _dict_to_block(d: dict) -> ContentBlock:
+    t = d["type"]
+    if t == "text":
+        return TextBlock(text=d["text"])
+    if t == "tool_use":
+        return ToolUseBlock(id=d["id"], name=d["name"], input=d["input"])
+    if t == "tool_result":
+        return ToolResultBlock(
+            tool_use_id=d["tool_use_id"],
+            content=d["content"],
+            is_error=d.get("is_error", False),
+        )
+    if t == "image":
+        return ImageBlock(media_type=d["media_type"], data=d["data"])
+    raise ValueError(f"Unknown block type: {t}")
+
+
+def _message_to_dict(msg: Message) -> dict:
+    return {
+        "role": msg.role,
+        "content": [_block_to_dict(b) for b in msg.content],
+    }
+
+
+def _dict_to_message(d: dict) -> Message:
+    return Message(
+        role=d["role"],
+        content=tuple(_dict_to_block(b) for b in d["content"]),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Session
+# ---------------------------------------------------------------------------
+
+@dataclasses.dataclass(frozen=True)
+class Session:
+    id: str
+    messages: tuple[Message, ...]
+    created_at: str
+    updated_at: str
+    total_usage: TokenUsage
+    project_path: Path
+    name: str = ""
+    tags: tuple[str, ...] = ()
+
+    @classmethod
+    def create(cls, project_path: Path) -> "Session":
+        """Create a new empty session with a unique 8-char hex ID."""
+        now = datetime.now(timezone.utc).isoformat()
+        session_id = uuid.uuid4().hex[:8]
+        return cls(
+            id=session_id,
+            messages=(),
+            created_at=now,
+            updated_at=now,
+            total_usage=TokenUsage(input_tokens=0, output_tokens=0),
+            project_path=project_path,
+        )
+
+    def add_message(self, msg: Message) -> "Session":
+        """Return a new Session with the message appended (immutable)."""
+        now = datetime.now(timezone.utc).isoformat()
+        return dataclasses.replace(
+            self,
+            messages=self.messages + (msg,),
+            updated_at=now,
+        )
+
+    def rename(self, name: str) -> "Session":
+        """Return a new Session with the given name (immutable)."""
+        now = datetime.now(timezone.utc).isoformat()
+        return dataclasses.replace(self, name=name, updated_at=now)
+
+    def add_tags(self, *tags: str) -> "Session":
+        """Return a new Session with tags merged (deduped, order-preserving, immutable)."""
+        merged = tuple(dict.fromkeys(self.tags + tags))
+        now = datetime.now(timezone.utc).isoformat()
+        return dataclasses.replace(self, tags=merged, updated_at=now)
+
+    def update_usage(self, usage: TokenUsage) -> "Session":
+        """Return a new Session with accumulated token usage (immutable)."""
+        now = datetime.now(timezone.utc).isoformat()
+        new_usage = TokenUsage(
+            input_tokens=self.total_usage.input_tokens + usage.input_tokens,
+            output_tokens=self.total_usage.output_tokens + usage.output_tokens,
+        )
+        return dataclasses.replace(self, total_usage=new_usage, updated_at=now)
+
+    def estimated_tokens(self) -> int:
+        """Rough token estimate: total character count divided by 4."""
+        char_count = 0
+        for msg in self.messages:
+            for block in msg.content:
+                if isinstance(block, TextBlock):
+                    char_count += len(block.text)
+                elif isinstance(block, ToolResultBlock):
+                    char_count += len(block.content)
+                elif isinstance(block, ToolUseBlock):
+                    char_count += len(block.name) + len(str(block.input))
+        return char_count // 4
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "messages": [_message_to_dict(m) for m in self.messages],
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "total_usage": {
+                "input_tokens": self.total_usage.input_tokens,
+                "output_tokens": self.total_usage.output_tokens,
+            },
+            "project_path": str(self.project_path),
+            "name": self.name,
+            "tags": list(self.tags),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Session":
+        return cls(
+            id=data["id"],
+            messages=tuple(_dict_to_message(m) for m in data["messages"]),
+            created_at=data["created_at"],
+            updated_at=data["updated_at"],
+            total_usage=TokenUsage(
+                input_tokens=data["total_usage"]["input_tokens"],
+                output_tokens=data["total_usage"]["output_tokens"],
+            ),
+            project_path=Path(data["project_path"]),
+            name=data.get("name", ""),
+            tags=tuple(data.get("tags", ())),
+        )
+
+
+# ---------------------------------------------------------------------------
+# SessionSummary
+# ---------------------------------------------------------------------------
+
+@dataclasses.dataclass(frozen=True)
+class SessionSummary:
+    id: str
+    project_path: Path
+    created_at: str
+    message_count: int
+    name: str = ""
+    tags: tuple[str, ...] = ()
+
+
+# ---------------------------------------------------------------------------
+# SessionManager
+# ---------------------------------------------------------------------------
+
+class SessionManager:
+    def __init__(self, session_dir: Path) -> None:
+        self._session_dir = session_dir
+        session_dir.mkdir(parents=True, exist_ok=True)
+
+    def save(self, session: Session) -> Path:
+        """Persist session as JSON; returns the file path."""
+        path = self._session_dir / f"{session.id}.json"
+        path.write_text(json.dumps(session.to_dict(), indent=2), encoding="utf-8")
+        return path
+
+    def load(self, session_id: str) -> Session:
+        """Load session by ID; raises FileNotFoundError if missing."""
+        path = self._session_dir / f"{session_id}.json"
+        if not path.exists():
+            raise FileNotFoundError(f"Session '{session_id}' not found at {path}")
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return Session.from_dict(data)
+
+    def list_sessions(self) -> list[SessionSummary]:
+        """Return session summaries sorted by modification time (most recent first)."""
+        files = sorted(
+            self._session_dir.glob("*.json"),
+            key=lambda p: p.stat().st_mtime,
+            reverse=True,
+        )
+        summaries: list[SessionSummary] = []
+        for f in files:
+            try:
+                data = json.loads(f.read_text(encoding="utf-8"))
+                summaries.append(
+                    SessionSummary(
+                        id=data["id"],
+                        project_path=Path(data["project_path"]),
+                        created_at=data["created_at"],
+                        message_count=len(data["messages"]),
+                        name=data.get("name", ""),
+                        tags=tuple(data.get("tags", ())),
+                    )
+                )
+            except (json.JSONDecodeError, KeyError):
+                continue
+        return summaries
+
+    def rename(self, session_id: str, name: str) -> Session:
+        """Rename a session and persist the change; returns updated Session."""
+        session = self.load(session_id)
+        renamed = session.rename(name)
+        self.save(renamed)
+        return renamed
+
+    def delete(self, session_id: str) -> bool:
+        """Delete a session file; returns True if deleted, False if not found."""
+        path = self._session_dir / f"{session_id}.json"
+        if not path.exists():
+            return False
+        path.unlink()
+        return True
+
+    def search(self, query: str) -> list[SessionSummary]:
+        """Return summaries whose name, project path, or tags contain query (case-insensitive)."""
+        query_lower = query.lower()
+        return [
+            s for s in self.list_sessions()
+            if query_lower in s.name.lower()
+            or query_lower in str(s.project_path).lower()
+            or any(query_lower in t.lower() for t in s.tags)
+        ]
+
+    def get_by_name(self, name: str) -> Session | None:
+        """Return the first Session whose name matches exactly, or None."""
+        for summary in self.list_sessions():
+            if summary.name == name:
+                return self.load(summary.id)
+        return None

llm_code/runtime/skill_resolver.py

@@ -0,0 +1,61 @@
+"""Skill dependency resolver — checks and auto-installs missing skill dependencies."""
+from __future__ import annotations
+
+import logging
+from packaging.version import Version
+
+from llm_code.runtime.skills import Skill, SkillDependency
+
+_log = logging.getLogger(__name__)
+
+
+def _get_llm_code_version() -> str:
+    """Return the installed llm-code version."""
+    try:
+        from importlib.metadata import version as pkg_version
+        return pkg_version("llm-code")
+    except Exception:
+        return "0.0.0"
+
+
+class SkillResolver:
+    """Check and resolve skill dependencies."""
+
+    def __init__(
+        self,
+        installed_skills: set[str],
+        installer: object,
+        max_depth: int = 3,
+    ) -> None:
+        self._installed = installed_skills
+        self._installer = installer
+        self._max_depth = max_depth
+
+    def find_missing(self, skill: Skill) -> list[SkillDependency]:
+        """Return list of dependencies not currently installed."""
+        return [dep for dep in skill.depends if dep.name not in self._installed]
+
+    def _check_cycle(self, name: str, visited: frozenset[str]) -> None:
+        """Raise ValueError if name is already in the visited set."""
+        if name in visited:
+            raise ValueError(f"Circular dependency detected: '{name}' already in chain {sorted(visited)}")
+
+    def _check_depth(self, depth: int) -> None:
+        """Raise ValueError if depth exceeds max_depth."""
+        if depth > self._max_depth:
+            raise ValueError(f"Dependency depth {depth} exceeds max depth {self._max_depth}")
+
+    def check_min_version(self, skill: Skill) -> list[str]:
+        """Check if llm-code version satisfies skill's min_version. Return warnings."""
+        if not skill.min_version:
+            return []
+        current = _get_llm_code_version()
+        try:
+            if Version(current) < Version(skill.min_version):
+                return [
+                    f"Skill '{skill.name}' requires llm-code >= {skill.min_version}, "
+                    f"but current version is {current}"
+                ]
+        except Exception:
+            return [f"Could not compare versions: current={current}, required={skill.min_version}"]
+        return []

llm_code/runtime/skills.py

@@ -0,0 +1,133 @@
+"""Skills system: load and classify SKILL.md files into SkillSet."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+_FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n(.*)", re.DOTALL)
+
+
+@dataclass(frozen=True)
+class SkillDependency:
+    """A dependency on another skill."""
+
+    name: str
+    registry: str = ""  # empty = search all registries
+
+
+@dataclass(frozen=True)
+class Skill:
+    """A single skill loaded from a SKILL.md file."""
+
+    name: str
+    description: str
+    content: str
+    auto: bool = False
+    trigger: str = ""
+    version: str = ""
+    tags: tuple[str, ...] = ()
+    model: str = ""
+    depends: tuple[SkillDependency, ...] = ()
+    min_version: str = ""
+
+    def __post_init__(self) -> None:
+        # If trigger not set (empty string), default it to name.
+        # Because frozen=True we must use object.__setattr__.
+        if not self.trigger:
+            object.__setattr__(self, "trigger", self.name)
+
+
+@dataclass(frozen=True)
+class SkillSet:
+    """Container for classified skills."""
+
+    auto_skills: tuple[Skill, ...]
+    command_skills: tuple[Skill, ...]
+
+
+class SkillLoader:
+    """Loads skills from directories."""
+
+    @staticmethod
+    def load_skill(path: Path) -> Skill:
+        """Parse a SKILL.md file and return a Skill."""
+        text = path.read_text(encoding="utf-8")
+        m = _FRONTMATTER_RE.match(text)
+        if not m:
+            raise ValueError(f"Invalid SKILL.md format: {path}")
+
+        frontmatter_raw, content = m.group(1), m.group(2)
+
+        try:
+            meta = yaml.safe_load(frontmatter_raw) or {}
+        except yaml.YAMLError:
+            meta = {}
+
+        name = str(meta.get("name", ""))
+        description = str(meta.get("description", ""))
+        auto_raw = meta.get("auto", False)
+        auto = auto_raw is True or str(auto_raw).lower() in ("true", "yes", "1")
+        trigger = str(meta.get("trigger", ""))
+
+        version = str(meta.get("version", ""))
+        model = str(meta.get("model", ""))
+        min_version = str(meta.get("min_version", ""))
+
+        tags_raw = meta.get("tags", [])
+        tags = tuple(str(t) for t in tags_raw) if isinstance(tags_raw, list) else ()
+
+        depends_raw = meta.get("depends", [])
+        depends: tuple[SkillDependency, ...] = ()
+        if isinstance(depends_raw, list):
+            deps = []
+            for item in depends_raw:
+                if isinstance(item, dict) and "name" in item:
+                    deps.append(SkillDependency(
+                        name=str(item["name"]),
+                        registry=str(item.get("registry", "")),
+                    ))
+            depends = tuple(deps)
+
+        return Skill(
+            name=name,
+            description=description,
+            content=content,
+            auto=auto,
+            trigger=trigger,
+            version=version,
+            tags=tags,
+            model=model,
+            depends=depends,
+            min_version=min_version,
+        )
+
+    @staticmethod
+    def load_from_dirs(dirs: list[Path]) -> SkillSet:
+        """Scan each directory for subdirs containing SKILL.md and classify."""
+        auto: list[Skill] = []
+        command: list[Skill] = []
+
+        for directory in dirs:
+            if not directory.is_dir():
+                continue
+            for subdir in sorted(directory.iterdir()):
+                if not subdir.is_dir():
+                    continue
+                skill_md = subdir / "SKILL.md"
+                if not skill_md.is_file():
+                    continue
+                if (subdir / ".disabled").exists():
+                    continue
+                skill = SkillLoader.load_skill(skill_md)
+                if skill.auto:
+                    auto.append(skill)
+                else:
+                    command.append(skill)
+
+        return SkillSet(
+            auto_skills=tuple(auto),
+            command_skills=tuple(command),
+        )

llm_code/runtime/speculative.py

@@ -0,0 +1,75 @@
+"""Speculative executor: pre-runs a tool in an OverlayFS before user confirmation."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from llm_code.runtime.overlay import OverlayFS
+from llm_code.tools.base import ToolResult
+
+if TYPE_CHECKING:
+    from llm_code.tools.base import Tool
+
+
+class SpeculativeExecutor:
+    """Pre-execute a tool against a Copy-on-Write overlay.
+
+    Usage::
+
+        executor = SpeculativeExecutor(tool, args, base_dir=cwd, session_id="abc")
+        result = executor.pre_execute()   # runs tool in overlay, real FS untouched
+        # … present result + pending changes to user …
+        executor.confirm()               # commit overlay → real FS
+        # or
+        executor.deny()                  # discard overlay, nothing written
+
+    The ``result`` returned by ``pre_execute()`` is cached; repeated calls
+    return the same object without re-running the tool.
+    """
+
+    def __init__(
+        self,
+        tool: "Tool",
+        args: dict,
+        base_dir: Path,
+        session_id: str,
+    ) -> None:
+        self._tool = tool
+        self._args = args
+        self.overlay = OverlayFS(base_dir=base_dir, session_id=session_id)
+        self._result: ToolResult | None = None
+        self._executed = False
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def pre_execute(self) -> ToolResult:
+        """Run the tool inside the overlay (idempotent; returns cached result)."""
+        if self._executed:
+            assert self._result is not None
+            return self._result
+
+        self._result = self._tool.execute(self._args, overlay=self.overlay)  # type: ignore[call-arg]
+        self._executed = True
+        return self._result
+
+    def confirm(self) -> None:
+        """Commit the overlay to the real filesystem.
+
+        Raises
+        ------
+        RuntimeError
+            If ``pre_execute()`` has not been called yet.
+        """
+        if not self._executed:
+            raise RuntimeError("call pre_execute() before confirm()")
+        self.overlay.commit()
+
+    def deny(self) -> None:
+        """Discard the overlay; nothing is written to the real filesystem."""
+        self.overlay.discard()
+
+    def list_pending_changes(self) -> list[Path]:
+        """Return the list of real paths that would be written on confirm()."""
+        return self.overlay.list_pending()