remaind 0.1.0__py3-none-any.whl

remaind/__init__.py

@@ -0,0 +1,3 @@
+"""Remaind — durable context for long-running agents."""
+
+__version__ = "0.1.0"

remaind/__main__.py

@@ -0,0 +1,10 @@
+"""Allow `python -m remaind ...` to invoke the CLI."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

remaind/_artifacts.py

@@ -0,0 +1,53 @@
+"""Content-addressed artifact store under ``.context/artifacts/``.
+
+Used by the event writer when a single payload exceeds the inline byte
+threshold (text) or is binary. Filenames are ``{sha256}.{ext}`` so identical
+content deduplicates automatically and the on-disk name is verifiable from
+the recorded ``content_hash``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class StoredArtifact:
+    path: Path
+    sha256: str
+    bytes: int
+
+
+class ArtifactStore:
+    def __init__(self, root: Path) -> None:
+        self._root = root
+
+    @property
+    def root(self) -> Path:
+        return self._root
+
+    def _ensure_root(self) -> None:
+        self._root.mkdir(parents=True, exist_ok=True)
+
+    def write_text(self, text: str) -> StoredArtifact:
+        data = text.encode("utf-8")
+        return self._write(data, suffix="txt")
+
+    def write_bytes(self, data: bytes) -> StoredArtifact:
+        if not isinstance(data, (bytes, bytearray)):
+            raise TypeError(
+                f"write_bytes expected bytes-like, got {type(data).__name__}"
+            )
+        return self._write(bytes(data), suffix="bin")
+
+    def _write(self, data: bytes, *, suffix: str) -> StoredArtifact:
+        digest = hashlib.sha256(data).hexdigest()
+        self._ensure_root()
+        path = self._root / f"{digest}.{suffix}"
+        if not path.exists():
+            tmp = path.with_suffix(path.suffix + ".tmp")
+            tmp.write_bytes(data)
+            tmp.replace(path)
+        return StoredArtifact(path=path, sha256=digest, bytes=len(data))

remaind/_atomic.py

@@ -0,0 +1,91 @@
+"""Atomic file writer with optional history snapshots.
+
+Implements the contract from `CONTRACT.md` §18:
+
+1. If the target exists and ``history_dir`` is supplied, copy the current
+   contents to ``history_dir/<microsecond-timestamp><ext>`` and fsync.
+2. Write the new contents to ``<target>.tmp`` + flush + fsync.
+3. Rename ``<target>.tmp`` over ``<target>``.
+4. fsync the parent directory where supported.
+
+Failures clean up the temp file before re-raising. The original target is
+never partially overwritten — either the new content is fully in place or
+the prior version is still on disk.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from ._timestamps import utc_now_filename_safe_us
+
+
+def _fsync_dir(dirpath: Path) -> None:
+    """fsync ``dirpath`` if the platform supports directory fsync."""
+    try:
+        fd = os.open(str(dirpath), os.O_RDONLY)
+    except OSError:
+        return
+    try:
+        os.fsync(fd)
+    except OSError:
+        # Best-effort on platforms without directory fsync (e.g. Windows).
+        pass
+    finally:
+        os.close(fd)
+
+
+def atomic_write_text(
+    target: Path,
+    content: str,
+    *,
+    history_dir: Path | None = None,
+    encoding: str = "utf-8",
+) -> Path | None:
+    """Atomically write ``content`` to ``target``.
+
+    When ``target`` already exists and ``history_dir`` is given, the current
+    contents are copied to a timestamped file inside ``history_dir`` before
+    the new write proceeds. Returns the history path if one was created,
+    else ``None``.
+    """
+    if not isinstance(content, str):
+        raise TypeError(
+            f"atomic_write_text requires str content, got {type(content).__name__}"
+        )
+
+    target = Path(target)
+    target.parent.mkdir(parents=True, exist_ok=True)
+
+    history_path: Path | None = None
+    if history_dir is not None and target.exists():
+        history_dir.mkdir(parents=True, exist_ok=True)
+        history_path = history_dir / f"{utc_now_filename_safe_us()}{target.suffix}"
+        # Read + write to copy the prior content so we capture the exact
+        # bytes that were on disk just before this update.
+        prior = target.read_bytes()
+        with open(history_path, "wb") as f:
+            f.write(prior)
+            f.flush()
+            os.fsync(f.fileno())
+        _fsync_dir(history_dir)
+
+    tmp = target.with_name(target.name + ".tmp")
+    try:
+        data = content.encode(encoding)
+        with open(tmp, "wb") as f:
+            f.write(data)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp, target)
+        _fsync_dir(target.parent)
+    except Exception:
+        if tmp.exists():
+            try:
+                tmp.unlink()
+            except OSError:
+                pass
+        raise
+
+    return history_path

remaind/_compaction.py

@@ -0,0 +1,59 @@
+"""Compaction-needed status surface.
+
+Combines ``estimated_context_tokens`` with the active threshold bands to
+answer two questions every caller cares about:
+
+* should compaction happen at all? (``compaction_needed``)
+* is it urgent — i.e. before the next substantial task step?
+  (``compaction_urgent``)
+
+The four band recommendations come straight from CONTRACT.md §14.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ._paths import ContextPaths
+from ._thresholds import Bands, band_for, compute_bands, load_default_profile
+
+_RECOMMENDATIONS: dict[str, str] = {
+    "normal": "continue — no compaction needed",
+    "warning": "mark compaction pending",
+    "hard": "compact before the next substantial task step",
+    "emergency": "compact immediately before adding context-heavy work",
+}
+
+
+@dataclass(frozen=True)
+class CompactionStatus:
+    estimated_tokens: int
+    band: str
+    bands: Bands
+    compaction_needed: bool
+    compaction_urgent: bool
+    recommendation: str = field(default="")
+
+
+def compute_compaction_status(state: dict, bands: Bands) -> CompactionStatus:
+    """Pure: classify ``state`` against precomputed ``bands``."""
+    tokens = int(state.get("estimated_context_tokens", 0))
+    band = band_for(tokens, bands)
+    return CompactionStatus(
+        estimated_tokens=tokens,
+        band=band,
+        bands=bands,
+        compaction_needed=band != "normal",
+        compaction_urgent=band in ("hard", "emergency"),
+        recommendation=_RECOMMENDATIONS[band],
+    )
+
+
+def compaction_status(base: Path) -> CompactionStatus:
+    """Read state + thresholds from ``base/.context`` and classify."""
+    paths = ContextPaths.at(Path(base))
+    state = json.loads(paths.state_json.read_text(encoding="utf-8"))
+    bands = compute_bands(load_default_profile(paths.thresholds_yaml))
+    return compute_compaction_status(state, bands)

remaind/_compactor.py

@@ -0,0 +1,158 @@
+"""Compaction pipeline primitives.
+
+This phase delivers the **pipeline** for compaction: source event selection,
+a candidate-generation interface, and a deterministic reference compactor.
+The structured-validation gate that decides whether to accept a candidate
+lands in the next phase.
+
+The reference compactor is rule-based and intentionally cheap. It does the
+minimum compaction work: preserves the existing state, rewrites the
+``## Compaction Notes`` section of the handover with the recent
+high-importance events, and reports which event IDs it preserved. Real
+LLM-driven compaction plugs in via the :class:`Compactor` Protocol later.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol
+
+from ._jsonl import iter_jsonl
+from ._paths import ContextPaths
+
+
+@dataclass(frozen=True)
+class CompactionSources:
+    """The raw material a compactor needs to produce candidate state/handover."""
+
+    window_events: list[dict] = field(default_factory=list)
+    importance_high: list[dict] = field(default_factory=list)
+    importance_critical: list[dict] = field(default_factory=list)
+    current_state: dict = field(default_factory=dict)
+    current_handover: str = ""
+    last_compaction_event_id: str | None = None
+
+
+@dataclass(frozen=True)
+class CompactionCandidate:
+    """Result of running a compactor.
+
+    The candidate is just a proposal. A separate validation step (Phase 10)
+    decides whether to accept it.
+    """
+
+    new_state: dict
+    new_handover: str
+    summary: str
+    preserved_event_ids: list[str]
+    rationale: str
+
+
+class Compactor(Protocol):
+    """Pluggable compactor surface for future LLM-driven plug-ins."""
+
+    def __call__(self, sources: CompactionSources) -> CompactionCandidate: ...
+
+
+def select_sources(base: Path) -> CompactionSources:
+    """Read state + handover + post-anchor events from ``base/.context``."""
+    paths = ContextPaths.at(Path(base))
+    state = json.loads(paths.state_json.read_text(encoding="utf-8"))
+    handover = paths.handover_md.read_text(encoding="utf-8")
+    last_compaction = state.get("last_compaction_event_id")
+    last_validation = state.get("last_validation_event_id")
+    # A completed compaction cycle writes a compaction event followed by a
+    # validation event; both must be excluded from the next window. We use
+    # whichever pointer is later as the effective anchor (validation, when
+    # both are set, since it's written second).
+    anchor: str | None = max(
+        (x for x in (last_compaction, last_validation) if x is not None),
+        default=None,
+    )
+
+    window: list[dict] = []
+    for _lineno, obj, err in iter_jsonl(paths.events_jsonl):
+        if err is not None or obj is None:
+            continue
+        # ULIDs sort lexicographically by time; same length and prefix means
+        # a plain string compare is correct.
+        if anchor is not None and obj.get("id", "") <= anchor:
+            continue
+        window.append(obj)
+
+    high = [e for e in window if int(e.get("importance", 0)) >= 2]
+    critical = [e for e in window if int(e.get("importance", 0)) >= 3]
+    return CompactionSources(
+        window_events=window,
+        importance_high=high,
+        importance_critical=critical,
+        current_state=state,
+        current_handover=handover,
+        last_compaction_event_id=last_compaction,
+    )
+
+
+_COMPACTION_NOTES_HEADING = "Compaction Notes"
+
+
+def _render_compaction_notes(high: Iterable[dict]) -> str:
+    high = list(high)
+    if not high:
+        return "- No high-importance events to preserve.\n"
+    lines = [f"- Preserved {len(high)} high-importance event(s):"]
+    for e in high:
+        critical = int(e.get("importance", 0)) >= 3
+        marker = " [critical]" if critical else ""
+        lines.append(
+            f"  - `{e['id']}` ({e['type']}, importance={e['importance']})"
+            f"{marker}: {e.get('summary', '').strip()}"
+        )
+    return "\n".join(lines) + "\n"
+
+
+def _replace_or_append_h2_section(text: str, heading: str, body: str) -> str:
+    """Replace an existing H2 ``heading`` block, or append one at the end."""
+    pattern = re.compile(
+        rf"^##\s+{re.escape(heading)}\s*$.*?(?=^##\s+|\Z)",
+        re.MULTILINE | re.DOTALL,
+    )
+    new_section = f"## {heading}\n\n{body.rstrip()}\n\n"
+    if pattern.search(text):
+        return pattern.sub(new_section, text)
+    return text.rstrip() + "\n\n" + new_section
+
+
+def default_compact(sources: CompactionSources) -> CompactionCandidate:
+    """Deterministic, rule-based reference compactor.
+
+    Keeps the active state intact and rewrites the handover's
+    ``## Compaction Notes`` section so the highest-importance events from
+    the window are explicitly summarized in the handover document.
+    """
+    new_state = dict(sources.current_state)
+    notes_body = _render_compaction_notes(sources.importance_high)
+    new_handover = _replace_or_append_h2_section(
+        sources.current_handover, _COMPACTION_NOTES_HEADING, notes_body
+    )
+
+    preserved_ids = [e["id"] for e in sources.importance_high if "id" in e]
+    summary = (
+        f"Preserved {len(preserved_ids)} high-importance event(s) "
+        f"from {len(sources.window_events)} window event(s)."
+    )
+    rationale = (
+        "default rule-based compactor: state preserved verbatim; handover "
+        "'## Compaction Notes' section rewritten to reflect the current "
+        "high-importance window."
+    )
+    return CompactionCandidate(
+        new_state=new_state,
+        new_handover=new_handover,
+        summary=summary,
+        preserved_event_ids=preserved_ids,
+        rationale=rationale,
+    )

remaind/_configs.py

@@ -0,0 +1,21 @@
+"""YAML config loaders for thresholds / redaction / tools."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def load_yaml_mapping(path: Path) -> dict[str, Any]:
+    """Parse ``path`` as YAML, requiring the top level to be a mapping."""
+    with path.open("r", encoding="utf-8") as f:
+        data = yaml.safe_load(f)
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ValueError(
+            f"{path}: top-level value must be a mapping, got {type(data).__name__}"
+        )
+    return data