rlmness-cli 0.2.0__py3-none-any.whl

rlmagent/harness/provider/wire.py

@@ -0,0 +1,189 @@
+"""Typed streaming signals emitted by model adapters and the agent wire protocol."""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from rlmagent.harness.contracts.transcript import CallBlock, ModelEntry, StrictModel
+from rlmagent.harness.contracts.values import JValue
+
+
+class StreamOpenEvent(StrictModel):
+    type: Literal["start"] = "start"
+    partial: ModelEntry
+
+
+class ContentOpenEvent(StrictModel):
+    type: Literal["text_start"] = "text_start"
+    content_index: int
+    partial: ModelEntry
+
+
+class ContentChunkEvent(StrictModel):
+    type: Literal["text_delta"] = "text_delta"
+    content_index: int
+    delta: str
+    partial: ModelEntry
+
+
+class ContentCloseEvent(StrictModel):
+    type: Literal["text_end"] = "text_end"
+    content_index: int
+    content: str
+    partial: ModelEntry
+
+
+class ReasoningOpenEvent(StrictModel):
+    type: Literal["thinking_start"] = "thinking_start"
+    content_index: int
+    partial: ModelEntry
+
+
+class ReasoningChunkEvent(StrictModel):
+    type: Literal["thinking_delta"] = "thinking_delta"
+    content_index: int
+    delta: str
+    partial: ModelEntry
+
+
+class ReasoningCloseEvent(StrictModel):
+    type: Literal["thinking_end"] = "thinking_end"
+    content_index: int
+    content: str
+    partial: ModelEntry
+
+
+class CallOpenEvent(StrictModel):
+    type: Literal["toolcall_start"] = "toolcall_start"
+    content_index: int
+    partial: ModelEntry
+
+
+class CallChunkEvent(StrictModel):
+    type: Literal["toolcall_delta"] = "toolcall_delta"
+    content_index: int
+    delta: str
+    partial: ModelEntry
+
+
+class CallCloseEvent(StrictModel):
+    type: Literal["toolcall_end"] = "toolcall_end"
+    content_index: int
+    tool_call: CallBlock
+    partial: ModelEntry
+
+
+CompletionCause = Literal["stop", "length", "toolUse"]
+FaultCause = Literal["aborted", "error"]
+
+
+class StreamCloseEvent(StrictModel):
+    type: Literal["done"] = "done"
+    reason: CompletionCause
+    message: ModelEntry
+
+
+class StreamFaultEvent(StrictModel):
+    type: Literal["error"] = "error"
+    reason: FaultCause
+    error: ModelEntry
+
+
+type WireEvent = Annotated[
+    StreamOpenEvent
+    | StreamCloseEvent
+    | StreamFaultEvent
+    | ContentOpenEvent
+    | ContentChunkEvent
+    | ContentCloseEvent
+    | ReasoningOpenEvent
+    | ReasoningChunkEvent
+    | ReasoningCloseEvent
+    | CallOpenEvent
+    | CallChunkEvent
+    | CallCloseEvent
+    | SourceRetryEvent,
+    Field(discriminator="type"),
+]
+
+
+class SourceStartEvent(BaseModel):
+    """Signals that a new model completion is being streamed."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["response_start"] = "response_start"
+    model: str
+
+
+class SourceRetryEvent(BaseModel):
+    """Adapter is backing off and reattempting after a transient failure."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["retry"] = "retry"
+    attempt: int
+    max_attempts: int
+    delay_seconds: float
+    message: str
+    data: dict[str, JValue] | None = None
+
+
+class SourceTextDelta(BaseModel):
+    """An incremental chunk of plain text from the model."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["text_delta"] = "text_delta"
+    delta: str
+
+
+class SourceThinkingDelta(BaseModel):
+    """An incremental chunk of reasoning output from the model."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["thinking_delta"] = "thinking_delta"
+    delta: str
+
+
+class SourceCallEvent(BaseModel):
+    """A fully resolved tool invocation emitted by the model."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["tool_call"] = "tool_call"
+    tool_call: CallBlock
+
+
+class SourceEndEvent(BaseModel):
+    """The model response has been fully received and assembled."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["response_end"] = "response_end"
+    message: ModelEntry
+    finish_reason: str | None = None
+
+
+class SourceErrorEvent(BaseModel):
+    """An adapter-level fault surfaced to the harness for display or recovery."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["error"] = "error"
+    message: str
+    data: dict[str, JValue] | None = None
+
+
+type SourceEvent = (
+    SourceStartEvent
+    | SourceRetryEvent
+    | SourceTextDelta
+    | SourceThinkingDelta
+    | SourceCallEvent
+    | SourceEndEvent
+    | SourceErrorEvent
+)

rlmagent/harness/session/__init__.py

@@ -0,0 +1,5 @@
+"""Append-only, event-sourced session persistence."""
+
+from rlmagent.harness.session.index import SessionCatalog, SessionMeta
+
+__all__ = ["SessionCatalog", "SessionMeta"]

rlmagent/harness/session/index.py

@@ -0,0 +1,218 @@
+"""Lightweight session metadata index backed by a JSONL file."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, replace
+from pathlib import Path
+from time import time
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from rlmagent.harness.session.store import jsonl_lines
+
+# ---------------------------------------------------------------------------
+# Serialization model
+# ---------------------------------------------------------------------------
+
+
+class SessionMetaWire(BaseModel):
+    """Pydantic model for (de)serializing a single index entry."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    session_id: str
+    vault_path: str
+    cwd: str
+    model: str
+    provider: str
+    title: str | None = None
+    created_at: float = Field(default_factory=time)
+    updated_at: float = Field(default_factory=time)
+    inference_provider: str | None = None
+    inference_provider_mode: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Runtime representation
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class SessionMeta:
+    """Immutable snapshot of session metadata for runtime use."""
+
+    session_id: str
+    vault_path: str
+    cwd: str
+    model: str
+    provider: str
+    title: str | None
+    created_at: float
+    updated_at: float
+    # Backend pin for routed providers, and whether it was learned or chosen.
+    inference_provider: str | None = None
+    inference_provider_mode: str | None = None
+
+    def to_wire(self) -> SessionMetaWire:
+        """Convert to a serializable wire model."""
+        return SessionMetaWire(
+            session_id=self.session_id,
+            vault_path=self.vault_path,
+            cwd=self.cwd,
+            model=self.model,
+            provider=self.provider,
+            title=self.title,
+            created_at=self.created_at,
+            updated_at=self.updated_at,
+            inference_provider=self.inference_provider,
+            inference_provider_mode=self.inference_provider_mode,
+        )
+
+
+def _wire_to_meta(wire: SessionMetaWire) -> SessionMeta:
+    """Convert a wire model to the frozen runtime representation."""
+    return SessionMeta(
+        session_id=wire.session_id,
+        vault_path=wire.vault_path,
+        cwd=wire.cwd,
+        model=wire.model,
+        provider=wire.provider,
+        title=wire.title,
+        created_at=wire.created_at,
+        updated_at=wire.updated_at,
+        inference_provider=wire.inference_provider,
+        inference_provider_mode=wire.inference_provider_mode,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Catalog
+# ---------------------------------------------------------------------------
+
+_INDEX_FILENAME = "index.jsonl"
+
+
+class SessionCatalog:
+    """Persistent index of session metadata stored as JSONL."""
+
+    def __init__(self, sessions_dir: str | Path) -> None:
+        self._dir = Path(sessions_dir)
+        self._path = self._dir / _INDEX_FILENAME
+
+    @property
+    def path(self) -> Path:
+        """Absolute path to the backing ``index.jsonl``."""
+        return self._path
+
+    # ── factory helpers ───────────────────────────────────────────────
+
+    @staticmethod
+    def prepare(
+        *,
+        session_id: str,
+        vault_path: str | Path,
+        cwd: str,
+        model: str,
+        provider: str,
+        title: str | None = None,
+    ) -> SessionMeta:
+        """Build a ``SessionMeta`` without writing it to any index."""
+        now = time()
+        return SessionMeta(
+            session_id=session_id,
+            vault_path=str(vault_path),
+            cwd=cwd,
+            model=model,
+            provider=provider,
+            title=title,
+            created_at=now,
+            updated_at=now,
+        )
+
+    # ── writes ────────────────────────────────────────────────────────
+
+    def upsert(self, meta: SessionMeta) -> None:
+        """Insert or replace the entry for ``meta.session_id``."""
+        self._dir.mkdir(parents=True, exist_ok=True)
+        entries = self._load_deduped()
+        current = entries.get(meta.session_id)
+        if current is not None and meta.updated_at < current.updated_at:
+            return
+        entries[meta.session_id] = meta
+
+        payload = "".join(
+            entry.to_wire().model_dump_json(exclude_none=True) + "\n"
+            for entry in sorted(entries.values(), key=lambda m: m.updated_at)
+        )
+        staged = self._path.with_name(f"{self._path.name}.tmp")
+        staged.write_text(payload, encoding="utf-8")
+        staged.replace(self._path)
+
+    def remove(self, session_ids: set[str]) -> None:
+        """Forget these sessions."""
+        entries = self._load_deduped()
+        payload = "".join(
+            entry.to_wire().model_dump_json(exclude_none=True) + "\n"
+            for entry in sorted(entries.values(), key=lambda m: m.updated_at)
+            if entry.session_id not in session_ids
+        )
+        staged = self._path.with_name(f"{self._path.name}.tmp")
+        staged.write_text(payload, encoding="utf-8")
+        staged.replace(self._path)
+
+    def touch(self, session_id: str) -> SessionMeta | None:
+        """Update the ``updated_at`` timestamp for *session_id*."""
+        existing = self.get(session_id)
+        if existing is None:
+            return None
+        refreshed = replace(existing, updated_at=time())
+        self.upsert(refreshed)
+        return refreshed
+
+    # ── reads ─────────────────────────────────────────────────────────
+
+    def list_all(self) -> list[SessionMeta]:
+        """Return all sessions ordered by ``updated_at`` descending."""
+        entries = self._load_deduped()
+        return sorted(entries.values(), key=lambda m: m.updated_at, reverse=True)
+
+    def get(self, session_id: str) -> SessionMeta | None:
+        """Look up a single session by its id, or ``None`` if absent."""
+        entries = self._load_deduped()
+        return entries.get(session_id)
+
+    def latest_for_cwd(self, cwd: str) -> SessionMeta | None:
+        """Return the most recently used session for *cwd*, or ``None``."""
+        candidates = [
+            m for m in self._load_deduped().values() if m.cwd == cwd
+        ]
+        if not candidates:
+            return None
+        return max(candidates, key=lambda m: m.updated_at)
+
+    # ── internals ─────────────────────────────────────────────────────
+
+    def _load_deduped(self) -> dict[str, SessionMeta]:
+        """Read every line, parse, and deduplicate by session_id."""
+        if not self._path.exists():
+            return {}
+
+        result: dict[str, SessionMeta] = {}
+        for line in jsonl_lines(self._path.read_text(encoding="utf-8")):
+            stripped = line.strip()
+            if not stripped:
+                continue
+            try:
+                raw = json.loads(stripped)
+                wire = SessionMetaWire.model_validate(raw)
+                meta = _wire_to_meta(wire)
+            except Exception:  # noqa: BLE001 - one bad line must not hide the rest
+                continue
+            existing = result.get(meta.session_id)
+            # The file is append-ordered, so on an equal timestamp the later
+            # line is the newer write. Coarse clocks (Windows ~15ms) tie often
+            # enough that a strict `>` silently discards fresh updates.
+            if existing is None or meta.updated_at >= existing.updated_at:
+                result[meta.session_id] = meta
+        return result

rlmagent/harness/session/lease.py

@@ -0,0 +1,66 @@
+"""OS-backed single-writer ownership for a saved session."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+
+class SessionBusy(RuntimeError):
+    pass
+
+
+def _record_holder(path: Path) -> None:
+    """Note who holds the lease, beside the lock file, so a refusal can name them."""
+    command = " ".join(os.path.basename(part) if i == 0 else part
+                       for i, part in enumerate(sys.argv[:3]))
+    try:
+        path.write_text(json.dumps({"pid": os.getpid(), "since": time.time(),
+                                    "command": command[:200]}), encoding="utf-8")
+    except OSError:
+        pass
+
+
+def describe_holder(path: Path) -> str:
+    """`` It is held by process 1234 (rlm-agent worker run), since 14:02.`` or empty."""
+    try:
+        info = json.loads(path.read_text(encoding="utf-8"))
+        pid = int(info["pid"])
+    except (OSError, ValueError, KeyError, TypeError):
+        return ""
+    since = time.strftime("%H:%M", time.localtime(float(info.get("since") or 0)))
+    command = str(info.get("command") or "").strip()
+    return (f" It is held by process {pid}" + (f" ({command})" if command else "")
+            + f", since {since}. Close that window or stop that worker to open it here.")
+
+
+def acquire(directory: Path, session_id: str):
+    if Path(session_id).name != session_id or any(c in session_id for c in "/\\:"):
+        raise ValueError("invalid session ID")
+    locks = directory / ".leases"
+    locks.mkdir(parents=True, exist_ok=True)
+    handle = (locks / f"{session_id}.lock").open("a+b")
+    try:
+        handle.seek(0)
+        try:
+            if os.name == "nt":
+                import msvcrt
+
+                msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, 1)
+            else:
+                import fcntl
+
+                fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError as exc:
+            raise SessionBusy(
+                f"Session {session_id} already has an active writer."
+                + describe_holder(locks / f"{session_id}.holder")
+            ) from exc
+        _record_holder(locks / f"{session_id}.holder")
+        return handle
+    except BaseException:
+        handle.close()
+        raise

rlmagent/harness/session/records.py

@@ -0,0 +1,118 @@
+"""Discriminated record types for the append-only session log."""
+
+from __future__ import annotations
+
+from time import time
+from typing import Annotated, Literal
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from rlmagent.harness.contracts.transcript import TranscriptEntry
+from rlmagent.harness.contracts.values import JValue
+
+
+def mint_id() -> str:
+    """Generate a hex identifier for a new session record."""
+    return uuid4().hex
+
+
+def now_epoch() -> float:
+    """Capture the wall-clock time as a float epoch."""
+    return time()
+
+
+FORMAT = 1  # raise when saved records change shape; older files have no field and count as 1
+
+
+class EntryBase(BaseModel):
+    """Shared header present on every record in the session log."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str = Field(default_factory=mint_id)
+    parent_id: str | None = None
+    timestamp: float = Field(default_factory=now_epoch)
+
+
+class TranscriptRecord(EntryBase):
+    """Wraps a single harness transcript entry for persistence."""
+
+    type: Literal["message"] = "message"
+    message: TranscriptEntry
+
+
+class ModelSwapRecord(EntryBase):
+    """Records a switch to a different model identifier."""
+
+    type: Literal["model_change"] = "model_change"
+    model: str
+
+
+class ReasoningLevelRecord(EntryBase):
+    """Records an adjustment to the reasoning depth setting."""
+
+    type: Literal["thinking_level_change"] = "thinking_level_change"
+    thinking_level: str | None = None
+
+
+class PruneRecord(EntryBase):
+    """A condensed summary that stands in for pruned earlier records on replay."""
+
+    type: Literal["compaction"] = "compaction"
+    summary: str
+    replaces_entry_ids: list[str] = Field(default_factory=list)
+
+
+class ForkSummaryRecord(EntryBase):
+    """Captures the synopsis of a diverged conversation branch."""
+
+    type: Literal["branch_summary"] = "branch_summary"
+    summary: str
+    branch_root_id: str | None = None
+
+
+class TagRecord(EntryBase):
+    """A user-assigned display name for the session."""
+
+    type: Literal["label"] = "label"
+    label: str
+
+
+class TipRecord(EntryBase):
+    """Points to the current head of the active conversation branch."""
+
+    type: Literal["leaf"] = "leaf"
+    entry_id: str | None = None
+
+
+class SessionMetaRecord(EntryBase):
+    """Top-level metadata stamped when a session is first created."""
+
+    type: Literal["session_info"] = "session_info"
+    format: int = FORMAT
+    created_at: float = Field(default_factory=now_epoch)
+    cwd: str | None = None
+    title: str | None = None
+
+
+class ExtensionRecord(EntryBase):
+    """Opaque payload owned by an application-level plugin."""
+
+    type: Literal["custom"] = "custom"
+    namespace: str
+    data: dict[str, JValue] = Field(default_factory=dict)
+
+
+type SessionRecord = Annotated[
+    TranscriptRecord
+    | ModelSwapRecord
+    | ReasoningLevelRecord
+    | PruneRecord
+    | ForkSummaryRecord
+    | TagRecord
+    | TipRecord
+    | SessionMetaRecord
+    | ExtensionRecord,
+    Field(discriminator="type"),
+]