hx-cli 0.1.0__py3-none-any.whl

hx/core/session.py

@@ -0,0 +1,208 @@
+"""Session persistence: append-only JSONL transcripts.
+
+Every message, tool result, usage record and compaction boundary is appended as
+it happens, so a crashed session is fully resumable and a compaction can be
+inspected or undone after the fact.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from dataclasses import asdict, dataclass, field, replace
+from pathlib import Path
+from typing import Any
+
+from hx.core.messages import Message, from_dict, to_dict
+from hx.core.usage import TurnUsage, UsageLedger
+from hx.paths import (
+    session_dir,
+    session_outputs_dir,
+    session_transcript_file,
+    sessions_dir,
+)
+
+
+@dataclass(slots=True)
+class SessionMeta:
+    session_id: str
+    cwd: str
+    created_at: float
+    updated_at: float
+    model: str
+    title: str | None = None
+    message_count: int = 0
+    parent_id: str | None = None
+    """Set for subagent sessions, which nest under their parent's directory."""
+
+
+@dataclass(slots=True)
+class Session:
+    """In-memory session state, mirrored to ``~/.hx/sessions/<id>/transcript.jsonl``."""
+
+    meta: SessionMeta
+    messages: list[Message] = field(default_factory=list)
+    usage: UsageLedger = field(default_factory=UsageLedger)
+    _pending: list[dict[str, Any]] = field(default_factory=list, repr=False)
+
+    def append(self, message: Message) -> None:
+        """Add to memory and flush the JSONL line. Ephemeral messages are recorded
+        but marked so resume does not replay stale reminders."""
+        self.messages.append(message)
+        self.meta.message_count = len(self.messages)
+        self.meta.updated_at = time.time()
+        self._pending.append({"kind": "message", "data": to_dict(message)})
+        self.flush()
+
+    def record_compaction(
+        self,
+        dropped: list[Message],
+        kept: list[Message],
+        summary: Message,
+    ) -> None:
+        """Retire the pre-compaction history and re-lay it as summary + kept.
+
+        The transcript is append-only, so the summary cannot be spliced in
+        ahead of the messages it replaces. Instead every live message is
+        flagged compacted and the new sequence is appended in order. Nothing is
+        deleted, so a resume replays exactly what happened and a future undo
+        still has the original turns to restore.
+        """
+        superseded = [*dropped, *kept]
+        for message in superseded:
+            message.compacted = True
+
+        self._pending.append({"kind": "compaction", "data": {"count": len(superseded)}})
+        self.append(summary)
+        for message in kept:
+            self.append(replace(message, compacted=False))
+
+    def record_usage(self, usage: TurnUsage) -> None:
+        self.usage.record(usage)
+        self._pending.append({"kind": "usage", "data": asdict(usage)})
+
+    def active_messages(self) -> list[Message]:
+        """Messages eligible for context: not ``compacted``, not ``ephemeral``."""
+        return [m for m in self.messages if not m.compacted and not m.ephemeral]
+
+    def flush(self) -> None:
+        if not self._pending:
+            return
+        path = session_transcript_file(self.meta.session_id)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("a", encoding="utf-8") as handle:
+            for record in self._pending:
+                handle.write(json.dumps(record) + "\n")
+        self._pending.clear()
+        self._write_meta()
+
+    def _write_meta(self) -> None:
+        path = session_dir(self.meta.session_id) / "meta.json"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(asdict(self.meta), indent=2))
+
+
+def new_session(cwd: Path, model: str, parent_id: str | None = None) -> Session:
+    """Create a session with a fresh id and its on-disk directory.
+
+    A subagent session nests under its parent (``<parent>/sub-<id>``), which
+    keeps its transcript alongside the work it belongs to and keeps it out of
+    the ``/resume`` listing, where it would be noise.
+    """
+    now = time.time()
+    session_id = f"{time.strftime('%Y%m%d-%H%M%S', time.localtime(now))}-{uuid.uuid4().hex[:8]}"
+    if parent_id:
+        if ".." in parent_id or parent_id.startswith("/"):
+            raise ValueError(f"unsafe parent session id: {parent_id!r}")
+        session_id = f"{parent_id}/sub-{uuid.uuid4().hex[:8]}"
+
+    meta = SessionMeta(
+        session_id=session_id,
+        cwd=str(cwd.resolve()),
+        created_at=now,
+        updated_at=now,
+        model=model,
+        parent_id=parent_id,
+    )
+    session_outputs_dir(session_id).mkdir(parents=True, exist_ok=True)
+    session = Session(meta=meta)
+    session._write_meta()
+    return session
+
+
+def load_session(session_id: str) -> Session:
+    """Rehydrate from JSONL.
+
+    Raises:
+        SessionNotFound: if the id has no transcript.
+    """
+    path = session_transcript_file(session_id)
+    meta_path = session_dir(session_id) / "meta.json"
+    if not meta_path.exists():
+        raise SessionNotFound(session_id)
+
+    meta = SessionMeta(**json.loads(meta_path.read_text()))
+    session = Session(meta=meta)
+    if not path.exists():
+        return session
+
+    with path.open(encoding="utf-8") as handle:
+        for line in handle:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                record = json.loads(line)
+            except json.JSONDecodeError:
+                # A torn final line from a crashed write costs one record, not the session.
+                continue
+            kind = record.get("kind")
+            if kind == "message":
+                session.messages.append(from_dict(record["data"]))
+            elif kind == "usage":
+                session.usage.record(TurnUsage(**record["data"]))
+            elif kind == "compaction":
+                # Compaction always supersedes a prefix of the live messages,
+                # so replaying in order reproduces the same partition.
+                remaining = int(record["data"]["count"])
+                for message in session.messages:
+                    if remaining <= 0:
+                        break
+                    if not message.compacted:
+                        message.compacted = True
+                        remaining -= 1
+    session.meta.message_count = len(session.messages)
+    return session
+
+
+def list_sessions(cwd: Path | None = None, limit: int = 20) -> list[SessionMeta]:
+    """Most-recent-first. Filtered to ``cwd`` when given - powers ``/resume``."""
+    root = sessions_dir()
+    if not root.is_dir():
+        return []
+
+    metas: list[SessionMeta] = []
+    for entry in root.iterdir():
+        meta_path = entry / "meta.json"
+        if not meta_path.is_file():
+            continue
+        try:
+            meta = SessionMeta(**json.loads(meta_path.read_text()))
+        except (OSError, json.JSONDecodeError, TypeError):
+            continue
+        if cwd is not None and meta.cwd != str(cwd.resolve()):
+            continue
+        metas.append(meta)
+
+    metas.sort(key=lambda m: m.updated_at, reverse=True)
+    return metas[:limit]
+
+
+def latest_session(cwd: Path) -> SessionMeta | None:
+    found = list_sessions(cwd, limit=1)
+    return found[0] if found else None
+
+
+class SessionNotFound(Exception):
+    pass

hx/core/usage.py

@@ -0,0 +1,129 @@
+"""Token and cost ledger.
+
+Feeds the status bar fields: context used, tokens used, cache-read/cache-write
+tokens, and session cost. OpenRouter returns an authoritative ``usage.cost``
+when ``usage: {include: true}`` is set on the request; we prefer that over our
+own arithmetic and only compute locally as a fallback.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # avoids a providers -> core import cycle at runtime
+    from hx.providers.models import ModelPricing
+
+
+@dataclass(slots=True)
+class TurnUsage:
+    """Usage for a single provider call."""
+
+    input_tokens: int = 0
+    """Prompt tokens billed at the full rate. Excludes ``cache_read_tokens``."""
+    output_tokens: int = 0
+    cache_read_tokens: int = 0
+    """Prompt tokens served from the provider's KV cache (billed at a discount)."""
+    cache_write_tokens: int = 0
+    """Prompt tokens written into the cache (billed at a premium on Anthropic)."""
+    reasoning_tokens: int = 0
+    cost_usd: float | None = None
+    """Provider-reported cost. ``None`` means fall back to local pricing."""
+    latency_ms: float = 0.0
+
+    @property
+    def prompt_tokens(self) -> int:
+        """Every prompt token, cached or not."""
+        return self.input_tokens + self.cache_read_tokens
+
+    @property
+    def cache_hit_rate(self) -> float:
+        """Cached share of prompt tokens, 0.0-1.0."""
+        total = self.prompt_tokens
+        return self.cache_read_tokens / total if total else 0.0
+
+
+@dataclass(slots=True)
+class UsageLedger:
+    """Running totals for a session."""
+
+    turns: list[TurnUsage] = field(default_factory=list)
+    context_tokens: int = 0
+    """Tokens currently occupied by the assembled context."""
+    context_window: int = 0
+
+    def record(self, usage: TurnUsage) -> None:
+        self.turns.append(usage)
+
+    @property
+    def total_input(self) -> int:
+        return sum(t.input_tokens for t in self.turns)
+
+    @property
+    def total_output(self) -> int:
+        return sum(t.output_tokens for t in self.turns)
+
+    @property
+    def total_cache_read(self) -> int:
+        return sum(t.cache_read_tokens for t in self.turns)
+
+    @property
+    def total_cache_write(self) -> int:
+        return sum(t.cache_write_tokens for t in self.turns)
+
+    @property
+    def total_cost_usd(self) -> float:
+        return sum(t.cost_usd or 0.0 for t in self.turns)
+
+    @property
+    def cache_hit_rate(self) -> float:
+        prompt = self.total_input + self.total_cache_read
+        return self.total_cache_read / prompt if prompt else 0.0
+
+    @property
+    def last_latency_ms(self) -> float:
+        return self.turns[-1].latency_ms if self.turns else 0.0
+
+    @property
+    def context_fraction(self) -> float:
+        """``context_tokens / context_window``, clamped to 0.0-1.0. Drives the
+        compaction trigger and the status bar gauge."""
+        if self.context_window <= 0:
+            return 0.0
+        return min(1.0, max(0.0, self.context_tokens / self.context_window))
+
+
+def compute_cost(usage: TurnUsage, pricing: ModelPricing) -> float:
+    """Local cost fallback when the provider reports none.
+
+    Cache reads and writes are priced separately from ordinary input tokens, and
+    ``input_tokens`` deliberately *excludes* cached tokens - double-counting here
+    silently inflates every cost display.
+    """
+    cache_read_rate = pricing.cache_read or pricing.prompt
+    cache_write_rate = pricing.cache_write or pricing.prompt
+    return (
+        usage.input_tokens * pricing.prompt
+        + usage.output_tokens * pricing.completion
+        + usage.cache_read_tokens * cache_read_rate
+        + usage.cache_write_tokens * cache_write_rate
+        + usage.reasoning_tokens * pricing.reasoning
+    )
+
+
+def format_cost(cost_usd: float) -> str:
+    """Human-readable cost for the status bar (e.g. ``$0.0431``)."""
+    if cost_usd >= 100:
+        return f"${cost_usd:,.0f}"
+    if cost_usd >= 1:
+        return f"${cost_usd:.2f}"
+    return f"${cost_usd:.4f}"
+
+
+def format_tokens(count: int) -> str:
+    """Compact token count (e.g. ``12.4k``, ``1.2M``)."""
+    if count < 1_000:
+        return str(count)
+    if count < 1_000_000:
+        return f"{count / 1_000:.1f}k".replace(".0k", "k")
+    return f"{count / 1_000_000:.1f}M".replace(".0M", "M")

hx/frontmatter.py

@@ -0,0 +1,80 @@
+"""YAML frontmatter parsing, shared by skills and agent definitions.
+
+Both are Markdown files whose first block is ``---``-delimited YAML. Keeping
+one parser means a malformed file fails the same way in both places.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+DELIMITER = "---"
+
+
+@dataclass(slots=True)
+class Document:
+    metadata: dict[str, Any]
+    body: str
+    path: Path
+
+
+def parse(text: str, path: Path) -> Document:
+    """Split frontmatter from body.
+
+    Raises:
+        FrontmatterError: when the block is unterminated or is not a mapping.
+            A file that silently parses as "no metadata" would be discovered
+            and then quietly ignored, which is harder to debug than a failure.
+    """
+    stripped = text.lstrip("")
+    if not stripped.startswith(DELIMITER):
+        return Document(metadata={}, body=stripped.strip(), path=path)
+
+    lines = stripped.splitlines()
+    closing = next(
+        (i for i, line in enumerate(lines[1:], start=1) if line.strip() == DELIMITER), None
+    )
+    if closing is None:
+        raise FrontmatterError(f"{path}: frontmatter opened with --- but never closed")
+
+    try:
+        metadata = yaml.safe_load("\n".join(lines[1:closing])) or {}
+    except yaml.YAMLError as exc:
+        raise FrontmatterError(f"{path}: invalid YAML frontmatter ({exc})") from exc
+
+    if not isinstance(metadata, dict):
+        raise FrontmatterError(f"{path}: frontmatter must be a mapping")
+
+    return Document(metadata=metadata, body="\n".join(lines[closing + 1 :]).strip(), path=path)
+
+
+def read(path: Path) -> Document:
+    try:
+        return parse(path.read_text(encoding="utf-8"), path)
+    except OSError as exc:
+        raise FrontmatterError(f"{path}: {exc}") from exc
+
+
+def require(document: Document, *keys: str) -> None:
+    missing = [key for key in keys if not str(document.metadata.get(key, "")).strip()]
+    if missing:
+        raise FrontmatterError(f"{document.path}: missing required field(s): {', '.join(missing)}")
+
+
+def string_tuple(value: Any) -> tuple[str, ...]:
+    """Accept either a YAML list or a comma-separated string."""
+    if value is None:
+        return ()
+    if isinstance(value, str):
+        return tuple(part.strip() for part in value.split(",") if part.strip())
+    if isinstance(value, list):
+        return tuple(str(item).strip() for item in value if str(item).strip())
+    return ()
+
+
+class FrontmatterError(Exception):
+    pass

hx/mcp/__init__.py

@@ -0,0 +1 @@
+"""Model Context Protocol client: external tool servers."""