hx-cli 0.1.0__py3-none-any.whl

hx/core/context.py

@@ -0,0 +1,271 @@
+"""Context assembly and cache-breakpoint placement.
+
+This module owns the single most performance-sensitive invariant in HX:
+**the request prefix must be byte-stable across turns.** Providers key their KV
+cache on an exact prefix match, so any reordering, timestamp, or per-turn
+counter placed above a breakpoint silently costs full price on every request.
+
+Layout, in order::
+
+    [1] system prompt          static for the session
+    [2] tool schemas           deterministic sort: builtins, then mcp__* alphabetical
+    [3] skills index           name + description only (progressive disclosure)
+    [4] project context        HX.md, cwd, git branch, top-level listing
+    --- breakpoint A (static) ---
+    [5] conversation history
+    --- breakpoint B (rolling, before the last few turns) ---
+    [6] latest user turn + late-injected ephemeral blocks
+
+Volatile data belongs below breakpoint B, via ``hx.core.lateinject``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, ClassVar
+
+from hx.core.messages import Message
+
+MAX_CACHE_BREAKPOINTS = 4
+"""Anthropic's per-request limit on explicit ``cache_control`` markers."""
+
+
+@dataclass(slots=True)
+class PromptSection:
+    """One addressable chunk of the prefix, tracked so ``/context`` can show a breakdown."""
+
+    name: str
+    text: str
+    tokens: int = 0
+
+
+@dataclass(slots=True)
+class AssembledContext:
+    """The exact payload handed to a provider, plus the accounting behind it.
+
+    ``messages`` holds the conversation only. The provider prepends the system
+    message when serialising, so ``breakpoints`` index the *payload* list where
+    position 0 is that system message.
+    """
+
+    system: list[PromptSection]
+    messages: list[Message]
+    tools: list[dict[str, Any]]
+    breakpoints: tuple[int, ...] = ()
+    """Indices into the payload message list that carry an explicit cache
+    breakpoint. Empty for implicit-caching models."""
+    total_tokens: int = 0
+    sections: list[PromptSection] = field(default_factory=list)
+
+    def system_text(self) -> str:
+        """Concatenated system sections, in declared order."""
+        return "\n\n".join(section.text for section in self.system if section.text)
+
+    def prefix_fingerprint(self) -> str:
+        """Stable hash of everything above the first breakpoint.
+
+        Tests assert this is unchanged across turns; a change means the cache
+        was invalidated.
+        """
+        digest = hashlib.sha256()
+        digest.update(self.system_text().encode())
+        digest.update(b"\x00")
+        digest.update(json.dumps(self.tools, sort_keys=True, separators=(",", ":")).encode())
+        return digest.hexdigest()
+
+
+class ContextBuilder:
+    """Assembles :class:`AssembledContext` from session state."""
+
+    #: Estimated tokens that must accumulate below the rolling breakpoint before
+    #: it is allowed to move. Advancing it every turn rewrites the cache
+    #: constantly and costs more than the hit it buys.
+    BREAKPOINT_HYSTERESIS_TOKENS: ClassVar[int] = 4_096
+    CHARS_PER_TOKEN: ClassVar[float] = 3.7
+
+    def __init__(
+        self,
+        system_prompt: str,
+        cwd: Path,
+        keep_recent_turns: int = 6,
+    ) -> None:
+        self.system_prompt = system_prompt
+        self.cwd = cwd
+        self.keep_recent_turns = keep_recent_turns
+        self._breakpoint_b: int | None = None
+        self._tokens_below_b: int = 0
+
+    def build(
+        self,
+        messages: list[Message],
+        tools: list[dict[str, Any]],
+        skills_index: str | None = None,
+        project_context: str | None = None,
+        cache_mode: str = "explicit",
+    ) -> AssembledContext:
+        """Assemble the request.
+
+        Args:
+            cache_mode: ``explicit`` (place ``cache_control`` markers),
+                ``implicit`` (rely on prefix stability alone), or ``none``.
+        """
+        system = [PromptSection("system", self.system_prompt)]
+        if skills_index:
+            system.append(PromptSection("skills", skills_index))
+        if project_context:
+            system.append(PromptSection("project", project_context))
+        for section in system:
+            section.tokens = self.estimate_tokens(section.text)
+
+        active = [m for m in messages if not m.compacted]
+        sorted_tools = sort_tools(tools)
+
+        breakpoints = self.place_breakpoints(active) if cache_mode == "explicit" else ()
+
+        sections = [
+            *system,
+            PromptSection(
+                "tools",
+                json.dumps(sorted_tools, sort_keys=True),
+                self.estimate_tokens(json.dumps(sorted_tools, sort_keys=True)),
+            ),
+            PromptSection(
+                "history",
+                "",
+                sum(self.estimate_tokens(_message_text(m)) for m in active),
+            ),
+        ]
+
+        return AssembledContext(
+            system=system,
+            messages=active,
+            tools=sorted_tools,
+            breakpoints=breakpoints,
+            total_tokens=sum(s.tokens for s in sections),
+            sections=sections,
+        )
+
+    def place_breakpoints(self, messages: list[Message]) -> tuple[int, ...]:
+        """Choose breakpoint indices into the payload list (0 = system message).
+
+        Breakpoint A sits on the system message, at the end of the static prefix.
+        Breakpoint B rolls forward to just before the last ``keep_recent_turns``
+        messages, and only moves once enough tokens have accumulated below it -
+        see :attr:`BREAKPOINT_HYSTERESIS_TOKENS`.
+        """
+        breakpoints = [0]
+        if len(messages) <= self.keep_recent_turns:
+            self._breakpoint_b = None
+            return tuple(breakpoints)
+
+        # +1 converts a conversation index into a payload index.
+        candidate = len(messages) - self.keep_recent_turns
+        if self._breakpoint_b is None:
+            self._breakpoint_b = candidate
+        else:
+            below = sum(
+                self.estimate_tokens(_message_text(m))
+                for m in messages[self._breakpoint_b : candidate]
+            )
+            if below >= self.BREAKPOINT_HYSTERESIS_TOKENS:
+                self._breakpoint_b = candidate
+
+        payload_index = self._breakpoint_b
+        if payload_index > 0:
+            breakpoints.append(payload_index)
+        return tuple(breakpoints[:MAX_CACHE_BREAKPOINTS])
+
+    def estimate_tokens(self, text: str) -> int:
+        """Cheap local token estimate for gauges and the compaction trigger.
+
+        Deliberately approximate; the authoritative counts come back from the
+        provider in ``usage``.
+        """
+        return int(len(text) / self.CHARS_PER_TOKEN) + 1 if text else 0
+
+
+def sort_tools(tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Canonical tool ordering: builtins first, then ``mcp__*``, each by name.
+
+    The serialised tool block sits in the cached prefix, so the order must not
+    depend on registration order, MCP connection order, or dict iteration.
+    """
+    return sorted(
+        tools, key=lambda t: (str(t.get("name", "")).startswith("mcp__"), t.get("name", ""))
+    )
+
+
+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 build_project_context(cwd: Path) -> str:
+    """Static per-session project preamble: HX.md contents, cwd, git branch, listing.
+
+    Computed once at startup and then frozen - refreshing it mid-session would
+    invalidate the prefix.
+    """
+    lines = [f"Working directory: {cwd}"]
+
+    branch = git_branch(cwd)
+    if branch:
+        lines.append(f"Git branch: {branch}")
+
+    entries = sorted(
+        p.name + ("/" if p.is_dir() else "") for p in cwd.iterdir() if not p.name.startswith(".")
+    )
+    if entries:
+        lines.append("Top level: " + ", ".join(entries[:60]))
+
+    for name in ("HX.md", ".hx/HX.md"):
+        candidate = cwd / name
+        if candidate.is_file():
+            lines.append(f"\n# Project instructions ({name})\n\n{candidate.read_text()}")
+            break
+
+    return "\n".join(lines)
+
+
+def git_branch(cwd: Path) -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=2,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return result.stdout.strip() or None if result.returncode == 0 else None
+
+
+SYSTEM_PROMPT = """\
+You are HX, an agentic coding assistant running in the user's terminal.
+
+Work directly on the user's codebase using the tools available to you. Prefer
+reading the relevant code over guessing at it. Make the change that was asked
+for - do not narrow it, widen it, or substitute a different one.
+
+Be concise. The user is reading your output in a terminal, so favour short
+direct answers and code over prose. Reference files as `path/to/file.py:42`.
+
+When a task takes several steps, track them so the user can see the plan and
+what remains. Report what actually happened: if a command failed, say so and
+show the output.
+"""
+
+
+def load_system_prompt(cwd: Path) -> str:
+    """The base HX system prompt. Contains no volatile values (no clock, no counters)."""
+    return SYSTEM_PROMPT

hx/core/events.py

@@ -0,0 +1,183 @@
+"""Async event bus.
+
+The agent core is a producer; the TUI and ``hx -p`` print mode are consumers.
+Keeping this one-way means the core never imports Textual and can be driven
+head-lessly in tests.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator
+from contextlib import suppress
+from dataclasses import dataclass, field
+from typing import Any, ClassVar
+
+
+@dataclass(slots=True)
+class Event:
+    """Base class for everything on the bus."""
+
+
+@dataclass(slots=True)
+class TurnStarted(Event):
+    turn_index: int
+    model: str
+
+
+@dataclass(slots=True)
+class TextDelta(Event):
+    """Streaming assistant text."""
+
+    text: str
+
+
+@dataclass(slots=True)
+class ThinkingDelta(Event):
+    text: str
+
+
+@dataclass(slots=True)
+class ToolCallStarted(Event):
+    tool_use_id: str
+    name: str
+    input: dict[str, Any]
+
+
+@dataclass(slots=True)
+class ToolCallProgress(Event):
+    """Incremental output (e.g. Bash stdout) shown live in the TUI, uncapped."""
+
+    tool_use_id: str
+    chunk: str
+
+
+@dataclass(slots=True)
+class ToolCallFinished(Event):
+    tool_use_id: str
+    is_error: bool
+    duration_ms: float
+    summary: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+    """Structured detail the renderer draws with - an edit's diff, a command's
+    exit code. Presentation only: the model never sees it."""
+
+
+@dataclass(slots=True)
+class PermissionRequested(Event):
+    """Core is blocked until a consumer answers via the paired future."""
+
+    request_id: str
+    tool_name: str
+    description: str
+    detail: str
+
+
+@dataclass(slots=True)
+class UsageUpdated(Event):
+    input_tokens: int
+    output_tokens: int
+    cache_read_tokens: int
+    cache_write_tokens: int
+    context_tokens: int
+    context_window: int
+    cost_usd: float
+
+
+@dataclass(slots=True)
+class TodosUpdated(Event):
+    todos: list[dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class SubagentStarted(Event):
+    subagent_id: str
+    agent_type: str
+    description: str
+
+
+@dataclass(slots=True)
+class SubagentFinished(Event):
+    subagent_id: str
+    is_error: bool
+
+
+@dataclass(slots=True)
+class CompactionStarted(Event):
+    reason: str
+
+
+@dataclass(slots=True)
+class CompactionFinished(Event):
+    tokens_before: int
+    tokens_after: int
+
+
+@dataclass(slots=True)
+class TurnFinished(Event):
+    turn_index: int
+    stop_reason: str
+
+
+@dataclass(slots=True)
+class ErrorRaised(Event):
+    message: str
+    recoverable: bool = True
+
+
+class EventBus:
+    """Fan-out pub/sub over ``asyncio.Queue``.
+
+    Slow consumers must not stall the agent loop: each subscriber gets its own
+    bounded queue and drops coalescible deltas rather than applying backpressure.
+    """
+
+    #: Event types safe to drop when a subscriber falls behind. Losing a text
+    #: delta degrades the render; losing a ToolCallFinished corrupts it.
+    COALESCIBLE: ClassVar[tuple[type[Event], ...]] = (
+        TextDelta,
+        ThinkingDelta,
+        ToolCallProgress,
+        UsageUpdated,
+    )
+
+    def __init__(self, max_queue: int = 1024) -> None:
+        self._max_queue = max_queue
+        self._queues: list[asyncio.Queue[Event | None]] = []
+        self._closed = False
+
+    def publish(self, event: Event) -> None:
+        """Non-blocking. Safe to call from inside the agent loop."""
+        if self._closed:
+            return
+        for queue in self._queues:
+            try:
+                queue.put_nowait(event)
+            except asyncio.QueueFull:
+                if isinstance(event, self.COALESCIBLE):
+                    continue
+                # Structural events must survive: evict the oldest item instead.
+                with suppress(asyncio.QueueEmpty):
+                    queue.get_nowait()
+                with suppress(asyncio.QueueFull):
+                    queue.put_nowait(event)
+
+    async def subscribe(self) -> AsyncIterator[Event]:
+        """Yield events until :meth:`close` is called."""
+        queue: asyncio.Queue[Event | None] = asyncio.Queue(maxsize=self._max_queue)
+        self._queues.append(queue)
+        try:
+            while True:
+                event = await queue.get()
+                if event is None:
+                    return
+                yield event
+        finally:
+            if queue in self._queues:
+                self._queues.remove(queue)
+
+    def close(self) -> None:
+        self._closed = True
+        for queue in self._queues:
+            with suppress(asyncio.QueueFull):
+                queue.put_nowait(None)

hx/core/lateinject.py

@@ -0,0 +1,121 @@
+"""Late injection of per-turn context.
+
+Anything that changes every turn - todo state, files modified since last read,
+plan-mode notices, permission-mode changes - must NOT live in the system prompt.
+Mutating the prefix invalidates the provider KV cache on every single turn,
+which is the single most expensive mistake this harness can make.
+
+Instead, injectors emit ``<hx-reminder>`` blocks that are appended to the tail
+of the newest user message and flagged ``ephemeral=True``. Before each turn the
+previous ephemeral blocks are stripped and regenerated. Nothing above the
+rolling cache breakpoint is ever rewritten.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass, replace
+
+from hx.core.messages import ContentBlock, Message, TextBlock
+
+REMINDER_OPEN = "<hx-reminder>"
+REMINDER_CLOSE = "</hx-reminder>"
+
+
+@dataclass(slots=True)
+class Injection:
+    """One block of late-injected context."""
+
+    source: str
+    """Injector name, for debugging via ``/context``."""
+    text: str
+    priority: int = 0
+    """Higher priority renders closer to the end of the message."""
+
+
+Injector = Callable[[], Injection | None]
+"""Returns the current injection, or ``None`` to contribute nothing this turn."""
+
+
+class InjectionRegistry:
+    """Holds the active injectors and applies them to a message list."""
+
+    def __init__(self) -> None:
+        self._injectors: dict[str, Injector] = {}
+
+    def register(self, name: str, injector: Injector) -> None:
+        self._injectors[name] = injector
+
+    def unregister(self, name: str) -> None:
+        self._injectors.pop(name, None)
+
+    def collect(self) -> list[Injection]:
+        """Run every injector, drop ``None`` results, sort by priority then name
+        so output is deterministic (a reordered prefix is a cache miss)."""
+        collected: list[Injection] = []
+        for name in sorted(self._injectors):
+            try:
+                injection = self._injectors[name]()
+            except Exception:
+                # A broken injector must not kill the turn.
+                continue
+            if injection is not None and injection.text.strip():
+                collected.append(injection)
+        return sorted(collected, key=lambda i: (i.priority, i.source))
+
+    def apply(self, messages: list[Message]) -> list[Message]:
+        """Return a copy of ``messages`` with stale ephemeral content stripped and
+        fresh injections appended to the final user message.
+
+        The input list is never mutated: the caller keeps the clean transcript
+        and only the assembled request carries injections.
+        """
+        cleaned = [strip_injections(m) if m.role == "user" else m for m in messages]
+
+        injections = self.collect()
+        if not injections:
+            return cleaned
+
+        block = render(injections)
+        tail = cleaned[-1] if cleaned else None
+        if tail is not None and tail.role == "user":
+            content = [*tail.content, TextBlock(text="\n\n" + block)]
+            cleaned[-1] = replace(tail, content=content, ephemeral=True)
+        else:
+            # No trailing user turn to ride on - carry the reminders on their own
+            # ephemeral message rather than touching anything already cached.
+            cleaned.append(Message(role="user", content=[TextBlock(text=block)], ephemeral=True))
+        return cleaned
+
+
+def strip_injections(message: Message) -> Message:
+    """Remove ``<hx-reminder>`` blocks from a message's text content."""
+    if REMINDER_OPEN not in _text_of(message):
+        return message
+
+    content: list[ContentBlock] = []
+    for block in message.content:
+        if isinstance(block, TextBlock):
+            stripped = _REMINDER_RE.sub("", block.text).rstrip()
+            if stripped:
+                content.append(TextBlock(text=stripped))
+        else:
+            content.append(block)
+    return replace(message, content=content, ephemeral=False)
+
+
+def render(injections: list[Injection]) -> str:
+    """Render injections into a single reminder-wrapped string."""
+    body = "\n\n".join(i.text.strip() for i in injections)
+    return f"{REMINDER_OPEN}\n{body}\n{REMINDER_CLOSE}"
+
+
+def _text_of(message: Message) -> str:
+    return "".join(b.text for b in message.content if isinstance(b, TextBlock))
+
+
+_REMINDER_RE = re.compile(
+    re.escape(REMINDER_OPEN) + r".*?" + re.escape(REMINDER_CLOSE),
+    re.DOTALL,
+)