hx-cli 0.1.0__py3-none-any.whl

hx/config.py

@@ -0,0 +1,277 @@
+"""Layered configuration.
+
+Precedence, lowest to highest::
+
+    defaults < ~/.hx/settings.json < <cwd>/.hx/settings.json < environment < CLI flags
+
+Settings are a plain dataclass so the whole config is hashable/serialisable and
+can be diffed in tests. Permission rules are kept as raw strings here; parsing
+into matchers is ``hx.permissions.engine``'s job.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from dataclasses import fields as dataclasses_fields
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+from hx.paths import project_settings_file, user_settings_file
+
+
+class PermissionMode(StrEnum):
+    """How aggressively HX asks before acting."""
+
+    PLAN = "plan"
+    """Read-only. No writes, no command execution."""
+
+    DEFAULT = "default"
+    """Ask before writes and command execution."""
+
+    ACCEPT_EDITS = "acceptEdits"
+    """Auto-approve file edits; still ask for command execution."""
+
+    BYPASS = "bypass"
+    """Approve everything. Sandbox still applies."""
+
+
+@dataclass(frozen=True, slots=True)
+class PermissionSettings:
+    mode: PermissionMode = PermissionMode.DEFAULT
+    allow: tuple[str, ...] = ()
+    ask: tuple[str, ...] = ()
+    deny: tuple[str, ...] = ()
+    sandbox: bool = True
+    """Use the OS sandbox when available (seatbelt / bubblewrap)."""
+    allow_network: bool = False
+    """Permit outbound network from sandboxed commands."""
+
+
+@dataclass(frozen=True, slots=True)
+class ContextSettings:
+    compact_at: float = 0.80
+    """Fraction of the model context window that triggers auto-compaction."""
+    keep_recent_turns: int = 6
+    """Turns kept verbatim across a compaction."""
+    tool_output_char_cap: int = 25_000
+    tool_output_line_cap: int = 2_000
+
+
+@dataclass(frozen=True, slots=True)
+class ModelSettings:
+    model: str = "anthropic/claude-sonnet-4.5"
+    subagent_model: str | None = None
+    """Model used by subagents. Falls back to ``model``."""
+    max_tokens: int = 8192
+    temperature: float | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class BashSettings:
+    timeout_seconds: int = 120
+    max_timeout_seconds: int = 600
+    shell: str | None = None
+    """Override the login shell used for the persistent Bash session."""
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    """Fully resolved configuration for one HX session."""
+
+    cwd: Path = field(default_factory=Path.cwd)
+    models: ModelSettings = field(default_factory=ModelSettings)
+    permissions: PermissionSettings = field(default_factory=PermissionSettings)
+    context: ContextSettings = field(default_factory=ContextSettings)
+    bash: BashSettings = field(default_factory=BashSettings)
+    theme: str = "dark"
+    telemetry: bool = False
+
+
+def load_settings(
+    cwd: Path | None = None,
+    overrides: dict[str, Any] | None = None,
+) -> Settings:
+    """Resolve the settings layers into a single :class:`Settings`.
+
+    Args:
+        cwd: Project root. Defaults to the process working directory.
+        overrides: CLI-flag layer, applied last.
+    """
+    root = (cwd or Path.cwd()).resolve()
+    layers = [
+        read_settings_file(user_settings_file()),
+        read_settings_file(project_settings_file(root)),
+        settings_from_env(dict(os.environ)),
+        overrides or {},
+    ]
+    merged = merge_layers(layers)
+    return _build_settings(merged, root)
+
+
+def _default(cls: type, name: str) -> Any:
+    """Default value of a dataclass field.
+
+    ``slots=True`` replaces class attributes with descriptors, so
+    ``ModelSettings.max_tokens`` is not the default - it is a member_descriptor.
+    """
+    for f in dataclasses_fields(cls):
+        if f.name == name:
+            return f.default
+    raise KeyError(name)
+
+
+def _build_settings(data: dict[str, Any], cwd: Path) -> Settings:
+    models = data.get("models", {})
+    permissions = data.get("permissions", {})
+    context = data.get("context", {})
+    bash = data.get("bash", {})
+
+    mode_raw = permissions.get("mode", PermissionMode.DEFAULT)
+    try:
+        mode = PermissionMode(mode_raw)
+    except ValueError as exc:
+        raise ConfigError(f"unknown permission mode: {mode_raw!r}") from exc
+
+    return Settings(
+        cwd=cwd,
+        models=ModelSettings(
+            model=models.get("model", _default(ModelSettings, "model")),
+            subagent_model=models.get("subagent_model"),
+            max_tokens=int(models.get("max_tokens", _default(ModelSettings, "max_tokens"))),
+            temperature=models.get("temperature"),
+        ),
+        permissions=PermissionSettings(
+            mode=mode,
+            allow=tuple(permissions.get("allow", ())),
+            ask=tuple(permissions.get("ask", ())),
+            deny=tuple(permissions.get("deny", ())),
+            sandbox=bool(permissions.get("sandbox", True)),
+            allow_network=bool(permissions.get("allow_network", False)),
+        ),
+        context=ContextSettings(
+            compact_at=float(context.get("compact_at", _default(ContextSettings, "compact_at"))),
+            keep_recent_turns=int(
+                context.get("keep_recent_turns", _default(ContextSettings, "keep_recent_turns"))
+            ),
+            tool_output_char_cap=int(
+                context.get(
+                    "tool_output_char_cap", _default(ContextSettings, "tool_output_char_cap")
+                )
+            ),
+            tool_output_line_cap=int(
+                context.get(
+                    "tool_output_line_cap", _default(ContextSettings, "tool_output_line_cap")
+                )
+            ),
+        ),
+        bash=BashSettings(
+            timeout_seconds=int(
+                bash.get("timeout_seconds", _default(BashSettings, "timeout_seconds"))
+            ),
+            max_timeout_seconds=int(
+                bash.get("max_timeout_seconds", _default(BashSettings, "max_timeout_seconds"))
+            ),
+            shell=bash.get("shell"),
+        ),
+        theme=data.get("theme", "dark"),
+        telemetry=bool(data.get("telemetry", False)),
+    )
+
+
+def read_settings_file(path: Path) -> dict[str, Any]:
+    """Read one ``settings.json`` layer. Missing file -> empty dict.
+
+    Raises:
+        ConfigError: if the file exists but is not valid JSON.
+    """
+    if not path.is_file():
+        return {}
+    try:
+        data = json.loads(path.read_text())
+    except json.JSONDecodeError as exc:
+        raise ConfigError(f"{path}: invalid JSON ({exc})") from exc
+    except OSError as exc:
+        raise ConfigError(f"{path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ConfigError(f"{path}: expected a JSON object")
+    return data
+
+
+def write_settings_file(path: Path, data: dict[str, Any]) -> None:
+    """Write a settings layer atomically (temp file + rename)."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n")
+    tmp.replace(path)
+
+
+#: Permission rule lists are unioned across layers rather than replaced - a
+#: project must be able to add a deny rule without discarding the user's.
+_UNIONED_KEYS = frozenset({"allow", "ask", "deny"})
+
+
+def merge_layers(layers: list[dict[str, Any]]) -> dict[str, Any]:
+    """Deep-merge settings layers. Later layers win; lists are replaced, not concatenated,
+    except permission rule lists which are unioned."""
+    result: dict[str, Any] = {}
+    for layer in layers:
+        _merge_into(result, layer)
+    return result
+
+
+def _merge_into(target: dict[str, Any], source: dict[str, Any]) -> None:
+    for key, value in source.items():
+        existing = target.get(key)
+        if isinstance(existing, dict) and isinstance(value, dict):
+            _merge_into(existing, value)
+        elif key in _UNIONED_KEYS and isinstance(existing, list) and isinstance(value, list):
+            target[key] = existing + [item for item in value if item not in existing]
+        else:
+            target[key] = value
+
+
+_ENV_MAP: dict[str, tuple[str, ...]] = {
+    "HX_MODEL": ("models", "model"),
+    "HX_SUBAGENT_MODEL": ("models", "subagent_model"),
+    "HX_MAX_TOKENS": ("models", "max_tokens"),
+    "HX_PERMISSION_MODE": ("permissions", "mode"),
+    "HX_SANDBOX": ("permissions", "sandbox"),
+    "HX_COMPACT_AT": ("context", "compact_at"),
+    "HX_THEME": ("theme",),
+}
+
+
+def settings_from_env(env: dict[str, str]) -> dict[str, Any]:
+    """Extract the ``HX_*`` environment layer (e.g. ``HX_MODEL``, ``HX_PERMISSION_MODE``)."""
+    layer: dict[str, Any] = {}
+    for name, path in _ENV_MAP.items():
+        if name not in env:
+            continue
+        cursor = layer
+        for part in path[:-1]:
+            cursor = cursor.setdefault(part, {})
+        cursor[path[-1]] = _coerce(env[name])
+    return layer
+
+
+def _coerce(raw: str) -> Any:
+    lowered = raw.strip().lower()
+    if lowered in {"true", "1", "yes"}:
+        return True
+    if lowered in {"false", "0", "no"}:
+        return False
+    try:
+        return int(raw)
+    except ValueError:
+        pass
+    try:
+        return float(raw)
+    except ValueError:
+        return raw
+
+
+class ConfigError(Exception):
+    """Raised for malformed configuration files."""

hx/core/__init__.py

@@ -0,0 +1 @@
+"""Headless agent core. Knows nothing about the TUI."""

hx/core/compaction.py

@@ -0,0 +1,245 @@
+"""Conversation compaction.
+
+Fires when the assembled context crosses ``context.compact_at`` of the model's
+window, or on an explicit ``/compact [instructions]``. Older turns are replaced
+by one structured summary; the last N turns and the full todo list survive
+verbatim. The pre-compaction messages stay in the session JSONL (flagged
+``compacted``) so resume and undo still work.
+
+Compaction reseeds the cache prefix by definition - that cost is accepted and
+surfaced in the status bar rather than hidden.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, ClassVar
+
+from hx.core.messages import (
+    Message,
+    TextBlock,
+    ThinkingBlock,
+    ToolResultBlock,
+    ToolUseBlock,
+)
+
+if TYPE_CHECKING:
+    from hx.core.context import ContextBuilder
+    from hx.providers.base import Provider
+
+SUMMARY_SECTIONS = (
+    "Goal",
+    "Decisions made",
+    "Files touched",
+    "Current state",
+    "Next steps",
+    "Open questions",
+)
+
+SUMMARY_MARKER = "<hx-compacted-summary>"
+SUMMARY_END = "</hx-compacted-summary>"
+
+SUMMARY_PROMPT = """\
+Summarise the conversation below so that work can continue without it.
+
+Write these sections, in order, using the exact headings:
+
+{sections}
+
+Be specific and concrete. Name files by path, record decisions with their
+reasons, and state exactly where the work stopped. Preserve anything the next
+turn would otherwise have to re-derive: chosen approaches, rejected approaches
+and why, error messages still unresolved, and commands that must be re-run.
+
+Do not summarise the summary instructions. Do not add commentary.
+{extra}
+--- conversation ---
+
+{transcript}
+"""
+
+
+@dataclass(slots=True)
+class CompactionResult:
+    summary: Message
+    kept: list[Message]
+    dropped: list[Message]
+    tokens_before: int
+    tokens_after: int
+
+
+class Compactor:
+    #: Cap on the summary itself. A summary that can grow without bound just
+    #: moves the context problem one turn later.
+    SUMMARY_MAX_TOKENS: ClassVar[int] = 2048
+    MIN_MESSAGES_TO_COMPACT: ClassVar[int] = 4
+
+    def __init__(
+        self,
+        provider: Provider | None = None,
+        model: str = "",
+        keep_recent_turns: int = 6,
+        context: ContextBuilder | None = None,
+    ) -> None:
+        self.provider = provider
+        self.model = model
+        self.keep_recent_turns = keep_recent_turns
+        self.context = context
+
+    def should_compact(self, context_fraction: float, threshold: float) -> bool:
+        return context_fraction >= threshold > 0
+
+    def split(self, messages: list[Message]) -> tuple[list[Message], list[Message]]:
+        """Partition into (to summarise, to keep verbatim).
+
+        The boundary snaps to a turn edge: never split an assistant tool-use
+        message from its tool results, or the next request is malformed.
+        """
+        if len(messages) <= self.keep_recent_turns:
+            return [], list(messages)
+
+        boundary = len(messages) - self.keep_recent_turns
+        while boundary > 0 and not _is_turn_edge(messages, boundary):
+            boundary -= 1
+
+        return list(messages[:boundary]), list(messages[boundary:])
+
+    async def compact(
+        self,
+        messages: list[Message],
+        instructions: str | None = None,
+    ) -> CompactionResult:
+        """Summarise via a provider call and assemble the replacement transcript."""
+        dropped, kept = self.split(messages)
+        if len(dropped) < self.MIN_MESSAGES_TO_COMPACT:
+            return CompactionResult(
+                summary=_summary_message("(nothing to compact)"),
+                kept=list(messages),
+                dropped=[],
+                tokens_before=self._estimate(messages),
+                tokens_after=self._estimate(messages),
+            )
+
+        text = await self._summarise(dropped, instructions)
+        summary = _summary_message(text)
+        return CompactionResult(
+            summary=summary,
+            kept=kept,
+            dropped=dropped,
+            tokens_before=self._estimate(messages),
+            tokens_after=self._estimate([summary, *kept]),
+        )
+
+    async def _summarise(self, messages: list[Message], instructions: str | None) -> str:
+        if self.provider is None:
+            # Without a provider there is nothing to call; fall back to a
+            # mechanical digest rather than silently dropping the history.
+            return _mechanical_summary(messages)
+
+        from hx.core.context import AssembledContext, PromptSection
+        from hx.providers.base import ProviderRequest, StreamDelta
+
+        prompt = self.build_summary_prompt(messages, instructions)
+        context = AssembledContext(
+            system=[PromptSection("system", "You write precise handover summaries.")],
+            messages=[Message(role="user", content=[TextBlock(text=prompt)])],
+            tools=[],
+        )
+        request = ProviderRequest(
+            context=context,
+            model=self.model,
+            max_tokens=self.SUMMARY_MAX_TOKENS,
+        )
+
+        parts: list[str] = []
+        async for item in self.provider.astream(request):
+            if isinstance(item, StreamDelta) and item.text:
+                parts.append(item.text)
+
+        return "".join(parts).strip() or _mechanical_summary(messages)
+
+    def build_summary_prompt(
+        self,
+        messages: list[Message],
+        instructions: str | None,
+    ) -> str:
+        """Prompt requesting the sections in :data:`SUMMARY_SECTIONS`."""
+        extra = f"\nAlso: {instructions.strip()}\n" if instructions else ""
+        return SUMMARY_PROMPT.format(
+            sections="\n".join(f"## {section}" for section in SUMMARY_SECTIONS),
+            extra=extra,
+            transcript=render_transcript(messages),
+        )
+
+    def _estimate(self, messages: list[Message]) -> int:
+        if self.context is not None:
+            return sum(self.context.estimate_tokens(_message_text(m)) for m in messages)
+        return sum(len(_message_text(m)) // 4 for m in messages)
+
+
+def _is_turn_edge(messages: list[Message], index: int) -> bool:
+    """True when a split before ``index`` leaves every tool call with its results."""
+    if index <= 0 or index >= len(messages):
+        return True
+    previous = messages[index - 1]
+    current = messages[index]
+    if previous.tool_uses():
+        return False
+    return not any(isinstance(block, ToolResultBlock) for block in current.content)
+
+
+def render_transcript(messages: list[Message]) -> str:
+    """Flatten messages to text for the summary prompt.
+
+    Rendering to text rather than replaying the structured messages keeps the
+    summary call free of tool-call pairing constraints, which a partial history
+    would otherwise violate.
+    """
+    lines: list[str] = []
+    for message in messages:
+        for block in message.content:
+            if isinstance(block, TextBlock):
+                lines.append(f"[{message.role}] {block.text}")
+            elif isinstance(block, ToolUseBlock):
+                lines.append(f"[{message.role}] calls {block.name}({block.input})")
+            elif isinstance(block, ToolResultBlock):
+                marker = "error" if block.is_error else "result"
+                lines.append(f"[tool {marker}] {_clip(block.content)}")
+            elif isinstance(block, ThinkingBlock):
+                continue
+    return "\n".join(lines)
+
+
+def _mechanical_summary(messages: list[Message]) -> str:
+    """Last-resort digest when no model is available to write one."""
+    users = [m.text() for m in messages if m.role == "user" and m.text()]
+    tools = sorted({b.name for m in messages for b in m.tool_uses()})
+    lines = ["## Goal", users[0][:500] if users else "(unknown)", "", "## Current state"]
+    lines.append(f"{len(messages)} earlier messages were compacted without a model summary.")
+    if tools:
+        lines.append(f"Tools used: {', '.join(tools)}.")
+    if len(users) > 1:
+        lines += ["", "## Open questions", *[f"- {text[:200]}" for text in users[1:6]]]
+    return "\n".join(lines)
+
+
+def _summary_message(text: str) -> Message:
+    body = f"{SUMMARY_MARKER}\nThis replaces the earlier conversation.\n\n{text}\n{SUMMARY_END}"
+    return Message(
+        role="user",
+        content=[TextBlock(text=body)],
+        metadata={"compaction_summary": True},
+    )
+
+
+def _message_text(message: Message) -> str:
+    parts: list[str] = []
+    for block in message.content:
+        text = getattr(block, "text", None) or getattr(block, "content", None)
+        if isinstance(text, str):
+            parts.append(text)
+    return "\n".join(parts)
+
+
+def _clip(text: str, limit: int = 2000) -> str:
+    return text if len(text) <= limit else text[:limit] + " … [clipped]"