hx-cli 0.1.0__py3-none-any.whl

hx/permissions/sandbox.py

@@ -0,0 +1,227 @@
+"""OS-level sandboxing for executed commands.
+
+macOS uses ``sandbox-exec`` with a generated Seatbelt profile; Linux uses
+``bubblewrap``. Both default to: read the filesystem, write only inside the
+project and the temp dir, no outbound network.
+
+If neither backend exists the sandbox degrades to a no-op - and says so in the
+status bar. Silently pretending to be sandboxed would be worse than being
+visibly unsandboxed.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import tempfile
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+
+
+class SandboxBackend(StrEnum):
+    SEATBELT = "seatbelt"
+    BUBBLEWRAP = "bubblewrap"
+    NONE = "none"
+
+
+CREDENTIAL_PATHS = (
+    "~/.ssh",
+    "~/.aws",
+    "~/.gnupg",
+    "~/.kube",
+    "~/.docker/config.json",
+    "~/.config/gh",
+    "~/.netrc",
+    "~/.npmrc",
+    "~/.pypirc",
+    "~/.hx/auth.json",
+)
+"""Denied even inside readable roots. A coding agent has no business reading
+these, and one prompt-injected `cat ~/.ssh/id_rsa` is all it takes."""
+
+
+@dataclass(slots=True)
+class SandboxPolicy:
+    writable_paths: tuple[Path, ...] = ()
+    readable_paths: tuple[Path, ...] = ()
+    deny_paths: tuple[Path, ...] = field(default_factory=tuple)
+    """Explicitly unreadable even inside readable roots - credential stores,
+    ``~/.ssh``, ``~/.aws``, and HX's own ``auth.json``."""
+    allow_network: bool = False
+    allow_subprocess: bool = True
+
+
+class Sandbox:
+    """Wraps a command so it runs under the platform's sandbox."""
+
+    def __init__(self, policy: SandboxPolicy, backend: SandboxBackend | None = None) -> None:
+        self.policy = policy
+        self._backend = backend if backend is not None else detect_backend()
+        self._profile_path: Path | None = None
+
+    @property
+    def backend(self) -> SandboxBackend:
+        return self._backend
+
+    @property
+    def active(self) -> bool:
+        """False when degraded to :attr:`SandboxBackend.NONE`."""
+        return self._backend is not SandboxBackend.NONE
+
+    def wrap(self, argv: list[str]) -> list[str]:
+        """Return the argv to actually exec."""
+        if self._backend is SandboxBackend.SEATBELT:
+            return ["/usr/bin/sandbox-exec", "-f", str(self._write_profile()), *argv]
+        if self._backend is SandboxBackend.BUBBLEWRAP:
+            return build_bwrap_argv(self.policy, argv)
+        return list(argv)
+
+    def profile_text(self) -> str:
+        """The generated Seatbelt profile - exposed so tests can assert on it and
+        ``/permissions`` can show it."""
+        return build_seatbelt_profile(self.policy)
+
+    def _write_profile(self) -> Path:
+        if self._profile_path is None or not self._profile_path.exists():
+            with tempfile.NamedTemporaryFile(
+                "w", suffix=".sb", prefix="hx-sandbox-", delete=False
+            ) as handle:
+                handle.write(self.profile_text())
+            self._profile_path = Path(handle.name)
+        return self._profile_path
+
+    def cleanup(self) -> None:
+        if self._profile_path is not None:
+            self._profile_path.unlink(missing_ok=True)
+            self._profile_path = None
+
+
+def detect_backend() -> SandboxBackend:
+    """Probe for ``sandbox-exec`` / ``bwrap`` on PATH."""
+    system = platform.system()
+    if system == "Darwin" and Path("/usr/bin/sandbox-exec").exists():
+        return SandboxBackend.SEATBELT
+    if system == "Linux" and shutil.which("bwrap"):
+        return SandboxBackend.BUBBLEWRAP
+    return SandboxBackend.NONE
+
+
+def default_policy(cwd: Path, allow_network: bool = False) -> SandboxPolicy:
+    """Writable: cwd and ``$TMPDIR``. Denied: credential paths. Network off."""
+    # gettempdir() resolves through /private on macOS; bind the resolved form,
+    # not the whole /var/folders tree, which would hand over every process's temp.
+    temp = Path(tempfile.gettempdir()).resolve()
+    writable = [cwd.resolve(), temp]
+
+    # Tool caches that live outside the project but must stay writable, or
+    # ordinary commands fail in confusing ways.
+    for extra in ("~/.cache", "~/Library/Caches"):
+        candidate = Path(extra).expanduser()
+        if candidate.is_dir():
+            writable.append(candidate.resolve())
+
+    return SandboxPolicy(
+        writable_paths=tuple(dict.fromkeys(writable)),
+        readable_paths=(Path("/"),),
+        deny_paths=tuple(_real(Path(p).expanduser()) for p in CREDENTIAL_PATHS),
+        allow_network=allow_network,
+    )
+
+
+def build_seatbelt_profile(policy: SandboxPolicy) -> str:
+    """Generate a Seatbelt profile.
+
+    Starts from ``(deny default)`` and allows explicitly. SBPL evaluates rules
+    in order with the last match winning, so the credential denials come after
+    the broad read allowance.
+
+    Paths are emitted as quoted ``subpath`` literals, not regexes, so a
+    directory named ``proj (1)`` cannot break out of the profile syntax.
+    """
+    lines = [
+        "(version 1)",
+        "(deny default)",
+        "",
+        ";; Process management",
+        "(allow process-fork)",
+        "(allow signal (target same-sandbox))",
+        "(allow sysctl-read)",
+        "(allow mach-lookup)",
+        "(allow ipc-posix-shm)",
+    ]
+    lines.append("(allow process-exec*)" if policy.allow_subprocess else "(deny process-exec*)")
+
+    lines += ["", ";; Reads"]
+    for path in policy.readable_paths or (Path("/"),):
+        lines.append(f"(allow file-read* (subpath {_sbpl_string(_real(path))}))")
+
+    lines += ["", ";; Writes"]
+    for path in policy.writable_paths:
+        lines.append(f"(allow file-write* (subpath {_sbpl_string(_real(path))}))")
+    for device in ("/dev/null", "/dev/stdout", "/dev/stderr", "/dev/tty", "/dev/urandom"):
+        lines.append(f"(allow file-write-data file-read-data (literal {_sbpl_string(device)}))")
+    lines.append('(allow file-write* (subpath "/private/var/folders"))')
+
+    lines += ["", ";; Network"]
+    lines.append("(allow network*)" if policy.allow_network else "(deny network*)")
+
+    if policy.deny_paths:
+        lines += ["", ";; Credentials - last match wins, so these override the read allowance"]
+        for path in policy.deny_paths:
+            lines.append(f"(deny file-read* (subpath {_sbpl_string(_real(path))}))")
+
+    return "\n".join(lines) + "\n"
+
+
+def _real(path: Path) -> Path:
+    """Resolve symlinks before emitting a path into a profile.
+
+    Seatbelt matches against the resolved real path, so an unresolved
+    ``/var/folders/...`` deny silently fails to cover the very files it names -
+    on macOS that path really lives under ``/private``.
+    """
+    try:
+        return path.resolve()
+    except OSError:
+        return path
+
+
+def _sbpl_string(path: Path | str) -> str:
+    """Quote a path as an SBPL string literal.
+
+    Only backslashes and double quotes are special inside a quoted literal, so
+    escaping those is sufficient - and unlike a regex, parentheses and dots in
+    the path carry no meaning.
+    """
+    text = str(path)
+    escaped = text.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+def build_bwrap_argv(policy: SandboxPolicy, argv: list[str]) -> list[str]:
+    """Generate the ``bwrap`` invocation: ``--ro-bind / /``, project bound
+    read-write, ``--unshare-net`` unless network is allowed."""
+    command = [
+        "bwrap",
+        "--ro-bind",
+        "/",
+        "/",
+        "--dev",
+        "/dev",
+        "--proc",
+        "/proc",
+        "--die-with-parent",
+    ]
+    for path in policy.writable_paths:
+        command += ["--bind", str(_real(path)), str(_real(path))]
+    for path in policy.deny_paths:
+        if path.exists():
+            # There is no "deny read" in bwrap; shadow the path with an empty dir.
+            command += ["--tmpfs", str(path)]
+    if not policy.allow_network:
+        command.append("--unshare-net")
+    if cwd := os.environ.get("PWD"):
+        command += ["--chdir", cwd]
+    return [*command, "--", *argv]

hx/providers/__init__.py

@@ -0,0 +1 @@
+"""Model providers. OpenRouter is the only real one for now."""

hx/providers/base.py

@@ -0,0 +1,77 @@
+"""Provider protocol.
+
+A provider converts an :class:`~hx.core.context.AssembledContext` into wire
+format, streams the response, and converts it back into core message types.
+All provider-specific quirks - cache markers, reasoning fields, tool-call
+encodings - stay behind this boundary.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+from hx.core.context import AssembledContext
+from hx.core.messages import StopReason
+from hx.core.usage import TurnUsage
+
+
+@dataclass(slots=True)
+class StreamDelta:
+    """A chunk off the wire."""
+
+    text: str | None = None
+    thinking: str | None = None
+    tool_use_id: str | None = None
+    tool_name: str | None = None
+    tool_input_json: str | None = None
+    """Partial JSON for a tool call; accumulated by the consumer."""
+
+
+@dataclass(slots=True)
+class StreamEnd:
+    stop_reason: StopReason
+    usage: TurnUsage = field(default_factory=TurnUsage)
+
+
+StreamItem = StreamDelta | StreamEnd
+
+
+@dataclass(slots=True)
+class ProviderRequest:
+    context: AssembledContext
+    model: str
+    max_tokens: int
+    temperature: float | None = None
+    stop_sequences: tuple[str, ...] = ()
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+@runtime_checkable
+class Provider(Protocol):
+    name: str
+
+    def astream(self, request: ProviderRequest) -> AsyncIterator[StreamItem]:
+        """Stream a completion. Must raise :class:`ProviderError` on failure.
+
+        Implementations are async generator functions, so this is declared as a
+        plain ``def`` returning an ``AsyncIterator`` rather than ``async def``.
+        """
+        ...
+
+    async def aclose(self) -> None: ...
+
+
+class ProviderError(Exception):
+    """Transport or API failure.
+
+    Attributes:
+        retryable: Whether the loop should retry with backoff (429, 5xx,
+            connection resets) rather than surfacing to the user.
+    """
+
+    def __init__(self, message: str, *, status: int | None = None, retryable: bool = False) -> None:
+        super().__init__(message)
+        self.status = status
+        self.retryable = retryable

hx/providers/fake.py

@@ -0,0 +1,87 @@
+"""Scripted provider for tests.
+
+Replays a canned sequence of deltas and tool calls so the entire agent loop -
+tool dispatch, output capping, compaction triggers, late injection,
+cancellation - is deterministic and runs offline.
+
+It also records every :class:`~hx.providers.base.ProviderRequest` it receives,
+which is what the prefix-stability tests assert against.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+
+from hx.core.messages import StopReason
+from hx.core.usage import TurnUsage
+from hx.providers.base import ProviderError, ProviderRequest, StreamDelta, StreamEnd, StreamItem
+
+
+class FakeProvider:
+    name = "fake"
+
+    def __init__(self, script: list[list[StreamItem]]) -> None:
+        """Args:
+        script: One list of stream items per expected turn, consumed in order.
+        """
+        self._script = list(script)
+        self._turn = 0
+        self._requests: list[ProviderRequest] = []
+        self.closed = False
+
+    async def astream(self, request: ProviderRequest) -> AsyncIterator[StreamItem]:
+        self._requests.append(request)
+        if self._turn >= len(self._script):
+            raise ProviderError(
+                f"FakeProvider script exhausted after {self._turn} turns; "
+                "the loop ran more turns than the test expected"
+            )
+        items = self._script[self._turn]
+        self._turn += 1
+        for item in items:
+            yield item
+
+    async def aclose(self) -> None:
+        self.closed = True
+
+    @property
+    def requests(self) -> list[ProviderRequest]:
+        """Every request seen, in order."""
+        return self._requests
+
+    def prefix_fingerprints(self) -> list[str]:
+        """Prefix hash per recorded request. Identical values across turns means
+        the KV cache stayed warm."""
+        return [r.context.prefix_fingerprint() for r in self._requests]
+
+
+def text_turn(text: str, *, usage: TurnUsage | None = None) -> list[StreamItem]:
+    """Script helper: a plain text response ending the turn."""
+    return [
+        StreamDelta(text=text),
+        StreamEnd(stop_reason=StopReason.END_TURN, usage=usage or TurnUsage()),
+    ]
+
+
+def tool_turn(
+    name: str,
+    tool_input: dict[str, object],
+    tool_use_id: str = "t1",
+    *,
+    text: str | None = None,
+    usage: TurnUsage | None = None,
+) -> list[StreamItem]:
+    """Script helper: a single tool call."""
+    items: list[StreamItem] = []
+    if text:
+        items.append(StreamDelta(text=text))
+    items.append(
+        StreamDelta(
+            tool_use_id=tool_use_id,
+            tool_name=name,
+            tool_input_json=json.dumps(tool_input, sort_keys=True),
+        )
+    )
+    items.append(StreamEnd(stop_reason=StopReason.TOOL_USE, usage=usage or TurnUsage()))
+    return items

hx/providers/models.py

@@ -0,0 +1,238 @@
+"""Model catalogue: context windows, pricing, and caching behaviour.
+
+Populated from OpenRouter's ``/api/v1/models``, cached to
+``~/.hx/models.json`` and refreshed on demand (``/models refresh``) or when the
+cache is older than a day. The registry drives the ``/model`` picker, the
+context gauge, and cost fallback maths.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any, ClassVar
+
+from hx.paths import models_cache_file
+
+
+class CacheMode(StrEnum):
+    EXPLICIT = "explicit"
+    """Requires ``cache_control`` breakpoints (Anthropic, Gemini)."""
+
+    IMPLICIT = "implicit"
+    """Caches automatically on a stable prefix (OpenAI, DeepSeek, Grok)."""
+
+    NONE = "none"
+
+
+@dataclass(frozen=True, slots=True)
+class ModelPricing:
+    """USD per token, as OpenRouter reports it."""
+
+    prompt: float = 0.0
+    completion: float = 0.0
+    cache_read: float = 0.0
+    cache_write: float = 0.0
+    reasoning: float = 0.0
+
+
+@dataclass(frozen=True, slots=True)
+class ModelInfo:
+    id: str
+    name: str
+    context_window: int
+    max_output_tokens: int
+    pricing: ModelPricing
+    cache_mode: CacheMode = CacheMode.NONE
+    supports_tools: bool = True
+    supports_reasoning: bool = False
+
+
+class ModelRegistry:
+    """Lookup and refresh for the model catalogue."""
+
+    #: Vendor prefixes whose models need explicit ``cache_control`` breakpoints.
+    EXPLICIT_CACHE_VENDORS: ClassVar[frozenset[str]] = frozenset({"anthropic", "google"})
+    #: Vendors that cache automatically on a stable prefix.
+    IMPLICIT_CACHE_VENDORS: ClassVar[frozenset[str]] = frozenset(
+        {"openai", "deepseek", "x-ai", "mistralai", "moonshotai", "qwen"}
+    )
+    CACHE_TTL_SECONDS: ClassVar[float] = 86_400.0
+
+    def __init__(self) -> None:
+        self._models: dict[str, ModelInfo] = {}
+        self._fetched_at: float = 0.0
+
+    def get(self, model_id: str) -> ModelInfo:
+        """Raises :class:`UnknownModel` if absent even after a cache refresh."""
+        if not self._models:
+            self.load_cache()
+        try:
+            return self._models[model_id]
+        except KeyError:
+            raise UnknownModel(model_id) from None
+
+    def get_or_default(self, model_id: str) -> ModelInfo:
+        """Never raises.
+
+        An unknown id yields a conservative placeholder rather than a crash: a
+        model missing from a stale catalogue should still be usable, it just
+        cannot show accurate cost or a real context gauge.
+        """
+        try:
+            return self.get(model_id)
+        except UnknownModel:
+            return ModelInfo(
+                id=model_id,
+                name=model_id,
+                context_window=128_000,
+                max_output_tokens=8192,
+                pricing=ModelPricing(),
+                cache_mode=infer_cache_mode(model_id),
+            )
+
+    def all(self) -> list[ModelInfo]:
+        if not self._models:
+            self.load_cache()
+        return sorted(self._models.values(), key=lambda m: m.id)
+
+    def search(self, query: str) -> list[ModelInfo]:
+        """Fuzzy match for the ``/model`` picker, ranked by match quality."""
+        needle = query.strip().lower()
+        if not needle:
+            return self.all()
+        scored: list[tuple[int, str, ModelInfo]] = []
+        for model in self.all():
+            haystack = f"{model.id} {model.name}".lower()
+            if needle in haystack:
+                score = 0 if model.id.lower().startswith(needle) else 1
+            elif _subsequence(needle, haystack):
+                score = 2
+            else:
+                continue
+            scored.append((score, model.id, model))
+        return [m for _, _, m in sorted(scored, key=lambda item: (item[0], item[1]))]
+
+    @property
+    def is_stale(self) -> bool:
+        return (time.time() - self._fetched_at) > self.CACHE_TTL_SECONDS
+
+    async def refresh(self, api_key: str) -> None:
+        """Fetch the live catalogue and rewrite the cache."""
+        from hx.providers.openrouter import fetch_models
+
+        raw = await fetch_models(api_key)
+        self._models = {}
+        for entry in raw:
+            try:
+                info = parse_model_entry(entry)
+            except (KeyError, TypeError, ValueError):
+                # One malformed catalogue entry must not cost us the whole list.
+                continue
+            self._models[info.id] = info
+        self._fetched_at = time.time()
+        self.save_cache()
+
+    def load_cache(self) -> None:
+        path = models_cache_file()
+        if not path.exists():
+            return
+        try:
+            payload = json.loads(path.read_text())
+        except (OSError, json.JSONDecodeError):
+            return
+        self._fetched_at = payload.get("fetched_at", 0.0)
+        self._models = {}
+        for entry in payload.get("models", []):
+            try:
+                info = parse_model_entry(entry)
+            except (KeyError, TypeError, ValueError):
+                continue
+            self._models[info.id] = info
+
+    def save_cache(self) -> None:
+        path = models_cache_file()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "fetched_at": self._fetched_at,
+            "models": [
+                {
+                    "id": m.id,
+                    "name": m.name,
+                    "context_length": m.context_window,
+                    "top_provider": {"max_completion_tokens": m.max_output_tokens},
+                    "pricing": {
+                        "prompt": str(m.pricing.prompt),
+                        "completion": str(m.pricing.completion),
+                        "input_cache_read": str(m.pricing.cache_read),
+                        "input_cache_write": str(m.pricing.cache_write),
+                        "internal_reasoning": str(m.pricing.reasoning),
+                    },
+                    "supported_parameters": (["tools"] if m.supports_tools else [])
+                    + (["reasoning"] if m.supports_reasoning else []),
+                }
+                for m in self.all()
+            ],
+        }
+        tmp = path.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps(payload, indent=2, sort_keys=True))
+        tmp.replace(path)
+
+
+def parse_model_entry(entry: dict[str, Any]) -> ModelInfo:
+    """Map one OpenRouter catalogue entry to a :class:`ModelInfo`."""
+    pricing_raw = entry.get("pricing") or {}
+    model_id = str(entry["id"])
+    top = entry.get("top_provider") or {}
+    context_window = int(entry.get("context_length") or top.get("context_length") or 0)
+    params = entry.get("supported_parameters") or []
+    return ModelInfo(
+        id=model_id,
+        name=str(entry.get("name") or model_id),
+        context_window=context_window or 128_000,
+        max_output_tokens=int(top.get("max_completion_tokens") or 0) or 8192,
+        pricing=ModelPricing(
+            prompt=_price(pricing_raw.get("prompt")),
+            completion=_price(pricing_raw.get("completion")),
+            cache_read=_price(pricing_raw.get("input_cache_read")),
+            cache_write=_price(pricing_raw.get("input_cache_write")),
+            reasoning=_price(pricing_raw.get("internal_reasoning")),
+        ),
+        cache_mode=infer_cache_mode(model_id),
+        supports_tools="tools" in params,
+        supports_reasoning="reasoning" in params,
+    )
+
+
+def _price(value: Any) -> float:
+    """OpenRouter reports prices as strings in USD per token."""
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def _subsequence(needle: str, haystack: str) -> bool:
+    it = iter(haystack)
+    return all(ch in it for ch in needle)
+
+
+def infer_cache_mode(model_id: str) -> CacheMode:
+    """Derive caching behaviour from the model's vendor prefix.
+
+    OpenRouter does not expose this in the catalogue, so it is keyed off the
+    ``vendor/`` prefix and kept in one place rather than scattered through the
+    provider.
+    """
+    vendor = model_id.split("/", 1)[0].lower()
+    if vendor in ModelRegistry.EXPLICIT_CACHE_VENDORS:
+        return CacheMode.EXPLICIT
+    if vendor in ModelRegistry.IMPLICIT_CACHE_VENDORS:
+        return CacheMode.IMPLICIT
+    return CacheMode.NONE
+
+
+class UnknownModel(Exception):
+    pass