rlmness-cli 0.2.0__py3-none-any.whl

rlmagent/harness/session/replay.py

@@ -0,0 +1,165 @@
+"""Reconstruct live conversation state from the session record tree."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from rlmagent.harness.contracts.transcript import (
+    PruneSummaryEntry,
+    TranscriptEntry,
+)
+from rlmagent.harness.session.records import (
+    ModelSwapRecord,
+    PruneRecord,
+    ReasoningLevelRecord,
+    SessionMetaRecord,
+    SessionRecord,
+    TagRecord,
+    TipRecord,
+    TranscriptRecord,
+)
+
+
+class TreeIntegrityError(ValueError):
+    """The record graph contains duplicates, cycles, or dangling references."""
+
+
+# ---------------------------------------------------------------------------
+# Lineage — walk the parent chain
+# ---------------------------------------------------------------------------
+
+
+def index_by_id(entries: list[SessionRecord]) -> dict[str, SessionRecord]:
+    """Map records by their id, raising on collisions."""
+    result: dict[str, SessionRecord] = {}
+    for entry in entries:
+        if entry.id in result:
+            raise TreeIntegrityError(f"Colliding record id: {entry.id}")
+        result[entry.id] = entry
+    return result
+
+
+def trace_to_entry(entries: list[SessionRecord], leaf_id: str) -> list[SessionRecord]:
+    """Walk parent pointers from ``leaf_id`` to the root, returned root-first."""
+    by_id = index_by_id(entries)
+    path: list[SessionRecord] = []
+    seen: set[str] = set()
+    current_id: str | None = leaf_id
+
+    while current_id is not None:
+        if current_id in seen:
+            raise TreeIntegrityError(f"Parent-chain cycle at record: {current_id}")
+        seen.add(current_id)
+        entry = by_id.get(current_id)
+        if entry is None:
+            raise TreeIntegrityError(f"Dangling parent reference: {current_id}")
+        path.append(entry)
+        current_id = entry.parent_id
+
+    path.reverse()
+    return path
+
+
+# ---------------------------------------------------------------------------
+# Projection — fold records -> live state
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ProjectedState:
+    """Result of projecting an ordered record list into live session state."""
+
+    transcript: list[TranscriptEntry] = field(default_factory=list)
+    record_ids: list[str] = field(default_factory=list)
+    model: str | None = None
+    thinking_level: str | None = None
+    title: str | None = None
+    cwd: str | None = None
+
+
+def _apply_prune(
+    rows: list[tuple[str, TranscriptEntry]],
+    record: PruneRecord,
+) -> list[tuple[str, TranscriptEntry]]:
+    """Replace the rows superseded by *record* with a single summary row."""
+    superseded = set(record.replaces_entry_ids)
+    summary = PruneSummaryEntry(summary=record.summary, tokens_before=0)
+
+    kept: list[tuple[str, TranscriptEntry]] = []
+    placed = False
+    for row_id, message in rows:
+        if row_id not in superseded:
+            kept.append((row_id, message))
+            continue
+        if not placed:
+            kept.append((record.id, summary))
+            placed = True
+
+    # A compaction that matched nothing still belongs in the transcript.
+    if not placed:
+        kept.append((record.id, summary))
+    return kept
+
+
+def project_records(records: list[SessionRecord]) -> ProjectedState:
+    """Fold an ordered list of session records into live conversation state."""
+    rows: list[tuple[str, TranscriptEntry]] = []
+    model: str | None = None
+    thinking_level: str | None = None
+    title: str | None = None
+    cwd: str | None = None
+
+    for record in records:
+        if isinstance(record, TranscriptRecord):
+            rows.append((record.id, record.message))
+        elif isinstance(record, PruneRecord):
+            rows = _apply_prune(rows, record)
+        elif isinstance(record, ModelSwapRecord):
+            model = record.model
+        elif isinstance(record, ReasoningLevelRecord):
+            thinking_level = record.thinking_level
+        elif isinstance(record, TagRecord):
+            title = record.label
+        elif isinstance(record, SessionMetaRecord):
+            if record.title:
+                title = record.title
+            if record.cwd:
+                cwd = record.cwd
+
+    return ProjectedState(
+        transcript=[message for _row_id, message in rows],
+        record_ids=[row_id for row_id, _message in rows],
+        model=model,
+        thinking_level=thinking_level,
+        title=title,
+        cwd=cwd,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Tip discovery
+# ---------------------------------------------------------------------------
+
+
+def find_tip(records: list[SessionRecord]) -> str | None:
+    """Return the entry_id from the most recent ``TipRecord``, or ``None``."""
+    for record in reversed(records):
+        if isinstance(record, TipRecord):
+            return record.entry_id
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Active-branch projection — the loader entry point
+# ---------------------------------------------------------------------------
+
+
+def project_active_branch(records: list[SessionRecord]) -> ProjectedState:
+    """Project only the active branch of the record tree."""
+    tip = find_tip(records)
+    if tip is None:
+        return project_records(records)
+    try:
+        return project_records(trace_to_entry(records, tip))
+    except TreeIntegrityError:
+        return project_records(records)

rlmagent/harness/session/store.py

@@ -0,0 +1,155 @@
+"""Append-only JSONL persistence for session records."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Protocol
+
+from pydantic import TypeAdapter, ValidationError
+
+from rlmagent.harness.session.records import FORMAT
+from rlmagent.harness.session.records import SessionRecord
+
+# ---------------------------------------------------------------------------
+# Serialization + migration
+# ---------------------------------------------------------------------------
+
+_RECORD_ADAPTER: TypeAdapter[SessionRecord] = TypeAdapter(SessionRecord)
+
+
+class RecordParseError(ValueError):
+    """A JSONL line could not be decoded into a valid session record."""
+
+
+def jsonl_lines(text: str) -> list[str]:
+    r"""Split JSONL text into records on ``\n`` only."""
+    return [line.rstrip("\r") for line in text.split("\n")]
+
+
+def serialize_record(entry: SessionRecord) -> str:
+    """Encode a single record to a JSONL line with no None fields."""
+    return _RECORD_ADAPTER.dump_json(entry, exclude_none=True).decode() + "\n"
+
+
+def deserialize_record(line: str, *, line_number: int | None = None) -> SessionRecord:
+    """Decode a single JSONL line, upgrading legacy shapes on the fly."""
+    location = f" on line {line_number}" if line_number is not None else ""
+    try:
+        raw = json.loads(line)
+        upgraded = _upgrade_entry(raw)
+        if upgraded.get("type") == "session_info" and upgraded.get("format", 1) > FORMAT:
+            raise ValueError("this session was saved by a newer rlm-agent; upgrade to open it")
+        return _RECORD_ADAPTER.validate_python(upgraded)
+    except (json.JSONDecodeError, ValidationError, TypeError, ValueError) as exc:
+        raise RecordParseError(f"Unreadable session record{location}: {exc}") from exc
+
+
+def deserialize_records(lines: list[str]) -> list[SessionRecord]:
+    """Decode all non-blank JSONL lines into session records."""
+    results: list[SessionRecord] = []
+    for index, line in enumerate(lines, start=1):
+        if not line.strip():
+            continue
+        results.append(deserialize_record(line, line_number=index))
+    return results
+
+
+def _upgrade_entry(value: Any) -> Any:
+    """Normalize a raw dict into the current record schema."""
+    if not isinstance(value, dict) or value.get("type") != "message":
+        return value
+    migrated = dict(value)
+    migrated["message"] = _upgrade_message(value.get("message"))
+    return migrated
+
+
+def _upgrade_message(value: Any) -> Any:
+    if not isinstance(value, dict):
+        return value
+    message = dict(value)
+    role = message.get("role")
+
+    if role == "user" and ("custom_type" in message or "customType" in message):
+        message["role"] = "custom"
+        message["customType"] = message.pop("custom_type", message.get("customType"))
+        message.pop("custom_type", None)
+        message.setdefault("display", True)
+        return message
+
+    if role == "assistant":
+        usage = message.get("usage")
+        if isinstance(usage, dict) and usage.get("cost") is None:
+            usage = dict(usage)
+            usage["cost"] = {}
+            message["usage"] = usage
+
+        content = message.get("content", "")
+        if isinstance(content, str):
+            blocks: list[Any] = []
+            if content:
+                blocks.append({"type": "text", "text": content})
+            blocks.extend(message.pop("tool_calls", message.pop("toolCalls", [])) or [])
+            message["content"] = blocks
+        elif "tool_calls" in message or "toolCalls" in message:
+            blocks = list(content or [])
+            blocks.extend(message.pop("tool_calls", message.pop("toolCalls", [])) or [])
+            message["content"] = blocks
+        return message
+
+    if role == "tool":
+        message["role"] = "toolResult"
+        message["toolName"] = message.pop("name", message.get("toolName", "unknown"))
+        message["toolCallId"] = message.pop("tool_call_id", message.get("toolCallId", ""))
+        message["isError"] = not bool(message.pop("ok", True))
+        content = message.get("content", "")
+        if isinstance(content, str):
+            message["content"] = [{"type": "text", "text": content}] if content else []
+        data = message.pop("data", None)
+        details = message.get("details")
+        if isinstance(data, dict) and isinstance(details, dict):
+            message["details"] = {**data, **details}
+        elif details is None and data is not None:
+            message["details"] = data
+        error = message.pop("error", None)
+        if error and not message["content"]:
+            message["content"] = [{"type": "text", "text": str(error)}]
+        return message
+
+    return message
+
+
+# ---------------------------------------------------------------------------
+# Storage
+# ---------------------------------------------------------------------------
+
+
+class SessionVault(Protocol):
+    """Contract for any backend that persists session records."""
+
+    async def append(self, entry: SessionRecord) -> None:
+        """Write a single record to the end of the log."""
+        ...
+
+    async def read_all(self) -> list[SessionRecord]:
+        """Load every record in the order it was written."""
+        ...
+
+
+class JsonlVault:
+    """File-backed vault that stores one JSON object per line."""
+
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+
+    async def append(self, entry: SessionRecord) -> None:
+        """Write a record, creating parent directories on first use."""
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self.path.open("a", encoding="utf-8") as file:
+            file.write(serialize_record(entry))
+
+    async def read_all(self) -> list[SessionRecord]:
+        """Load all records from disk. A missing file yields an empty list."""
+        if not self.path.exists():
+            return []
+        return deserialize_records(jsonl_lines(self.path.read_text(encoding="utf-8")))

rlmagent/harness/session/summary.py

@@ -0,0 +1,46 @@
+"""Aggregate a stored session into token and cost totals."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from rlmagent.harness.contracts.transcript import ModelEntry
+from rlmagent.harness.session.records import SessionRecord, TranscriptRecord
+
+
+@dataclass(frozen=True, slots=True)
+class RunSummary:
+    """Token and cost totals for a single session."""
+
+    session_id: str
+    model: str | None
+    provider: str | None
+    turns: int
+    input_tokens: int
+    output_tokens: int
+    cache_read_tokens: int
+    cache_write_tokens: int
+    total_tokens: int
+    cost_usd: float
+
+
+def summarize_records(session_id: str, records: list[SessionRecord]) -> RunSummary:
+    """Sum the usage of every assistant turn in *records*."""
+    replies = [
+        record.message
+        for record in records
+        if isinstance(record, TranscriptRecord) and isinstance(record.message, ModelEntry)
+    ]
+
+    return RunSummary(
+        session_id=session_id,
+        model=replies[-1].model if replies else None,
+        provider=replies[-1].provider if replies else None,
+        turns=len(replies),
+        input_tokens=sum(reply.usage.input for reply in replies),
+        output_tokens=sum(reply.usage.output for reply in replies),
+        cache_read_tokens=sum(reply.usage.cache_read for reply in replies),
+        cache_write_tokens=sum(reply.usage.cache_write for reply in replies),
+        total_tokens=sum(reply.usage.total_tokens for reply in replies),
+        cost_usd=sum(reply.usage.cost.total for reply in replies),
+    )

rlmagent/hints.py

@@ -0,0 +1,47 @@
+"""Short notes added to a cell's output when it failed in a way models often repeat."""
+
+from __future__ import annotations
+
+import re
+
+_RULES: list[tuple[re.Pattern, str]] = [
+    (re.compile(r"f-string: (expecting|unmatched|single '\}')|f-string: .*quote", re.I),
+     "Inside an f-string, use the other kind of quote for strings in the braces, or build "
+     "the value in a variable first."),
+    (re.compile(r"unterminated (triple-quoted )?string literal", re.I),
+     "A string was not closed. For text with quotes or many lines, use triple quotes or "
+     "write it to a variable in pieces."),
+    (re.compile(r"coroutine .* was never awaited|<coroutine object", re.I),
+     "A host function was called without await. Write `await read_file(...)`, not "
+     "`read_file(...)`."),
+    (re.compile(r"object (dict|list|str|NoneType) can't be used in 'await' expression", re.I),
+     "That function is not a coroutine; call it without await."),
+    (re.compile(r"'await' outside (async )?function", re.I),
+     "Top-level await works in a cell, but not inside a plain def; make it `async def` and "
+     "await the call."),
+    (re.compile(r"ModuleNotFoundError: No module named '([\w.]+)'"),
+     "The module is not installed in this kernel. In the sandbox, try "
+     "`import micropip; await micropip.install(...)` when the network is on, or do the work "
+     "with run() on the host."),
+    (re.compile(r"no response within \d+s|timed out after", re.I),
+     "The cell ran past its time limit. Start long commands with job_start(command) and "
+     "read them with job_read, or split the work into smaller cells."),
+    (re.compile(r"NameError: name 'FINAL' is not defined"),
+     "FINAL is only defined at the top level of the kernel; call it outside functions."),
+]
+
+EMPTY_CELL = ("The reply had no code to run. Answer with a Python cell; call FINAL(answer) "
+              "when the task is done.")
+
+
+def hint_for(code: str | None, output: str) -> str | None:
+    """One hint for what went wrong, or None when nothing familiar shows."""
+    if code is not None and not code.strip():
+        return EMPTY_CELL
+    for pattern, hint in _RULES:
+        if pattern.search(output):
+            return hint
+    return None
+
+
+__all__ = ["EMPTY_CELL", "hint_for"]

rlmagent/history.py

@@ -0,0 +1,92 @@
+"""The whole record of a session, readable from a cell after compaction has shortened it."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+MAX_ITEMS = 200
+MAX_TEXT = 20_000
+
+
+def _text(content) -> str:
+    if isinstance(content, str):
+        return content
+    parts = []
+    for part in content or []:
+        if not isinstance(part, dict):
+            continue
+        kind = part.get("type")
+        if kind == "text":
+            parts.append(part.get("text", ""))
+        elif kind == "toolCall":
+            parts.append(f"[calls {part.get('name')}: {json.dumps(part.get('arguments'))[:2000]}]")
+        elif kind == "image":
+            parts.append("[image]")
+    return "\n".join(parts)
+
+
+def _rows(path: Path) -> list[dict]:
+    rows = []
+    if not path.exists():
+        return rows
+    for line in path.read_text(encoding="utf-8").splitlines():
+        try:
+            row = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(row, dict):
+            rows.append(row)
+    return rows
+
+
+def conversation(vault: Path) -> list[dict]:
+    """Every message the session saved, in order, including ones compaction summarized away."""
+    found = []
+    for row in _rows(vault):
+        if row.get("type") == "message":
+            message = row.get("message") or {}
+            found.append({"role": message.get("role", "?"),
+                          "text": _text(message.get("content"))[:MAX_TEXT],
+                          "time": row.get("timestamp")})
+        elif row.get("type") == "compaction":
+            found.append({"role": "compaction", "text": str(row.get("summary", ""))[:MAX_TEXT],
+                          "time": row.get("timestamp")})
+    return found
+
+
+def agent_steps(events: Path, agent: str) -> list[dict]:
+    """One agent's steps from the run log: its code and what the code printed."""
+    steps: dict[int, dict] = {}
+    for row in _rows(events):
+        if row.get("run_id") != agent or not isinstance(row.get("step"), int):
+            continue
+        step = steps.setdefault(row["step"], {"step": row["step"], "code": "", "output": ""})
+        if row.get("kind") == "code_generated":
+            step["code"] = str(row.get("code") or "")[:MAX_TEXT]
+        elif row.get("kind") == "output_received":
+            step["output"] = str(row.get("output") or "")[:MAX_TEXT]
+    return [steps[n] for n in sorted(steps)]
+
+
+def make_history(vault_path, events_path):
+    """history() for agents; the two callables give the current files, or None."""
+
+    async def history(start: int = 0, end: int | None = None, agent: str | None = None) -> dict:
+        """The full record, with nothing lost to compaction: messages[start:end] of this
+        session, or with agent=RUN_ID that agent's steps (code and output). At most 200 items
+        per call; "total" tells you how many there are."""
+        if agent is None:
+            path = vault_path()
+            items = conversation(Path(path)) if path else []
+        else:
+            path = events_path()
+            items = agent_steps(Path(path), str(agent)) if path else []
+        stop = len(items) if end is None else int(end)
+        picked = items[int(start):stop][:MAX_ITEMS]
+        return {"total": len(items), "start": int(start), "items": picked}
+
+    return history
+
+
+__all__ = ["agent_steps", "conversation", "make_history"]

rlmagent/hooks/__init__.py

@@ -0,0 +1 @@
+"""rlm-agent hooks: lifecycle event hooks (before/after agent, before/after tool, on error). NEW."""

rlmagent/hooks/hooks.py

@@ -0,0 +1 @@
+"""Observability / verification hook seam (callbacks on the event stream). TODO."""

rlmagent/instructions.py

@@ -0,0 +1,157 @@
+"""System-prompt assembly."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+from rlmagent.skillset import Skill, build_skill_index
+from rlmagent.harness.contracts.tooling import ToolSpec
+
+_AGENTS_FILE = "AGENTS.md"
+
+_BASE_IDENTITY = """You are rlm-agent, a coding agent working in the user's project. Your main tool is a persistent Python kernel; your other tools read, write and edit files.
+
+Work carefully: read a file before editing it, make minimal focused changes, and verify your work by running a test or a command in the kernel when one is available. Prefer clear, direct answers over hedging."""
+
+
+def _tool_guidelines(tools: Sequence[ToolSpec]) -> str:
+    """Render each tool's ``prompt_snippet``/``prompt_guidelines``, skipping tools with neither."""
+    seen: set[str] = set()
+    sections: list[str] = []
+    for tool in tools:
+        parts: list[str] = []
+        if tool.prompt_snippet:
+            parts.append(tool.prompt_snippet)
+        for guideline in tool.prompt_guidelines:
+            text = guideline.strip()
+            if text and text not in seen:
+                seen.add(text)
+                parts.append(f"- {text}")
+        if parts:
+            sections.append(f"### {tool.name}\n" + "\n".join(parts))
+    if not sections:
+        return ""
+    return "## Tool guidelines\n\n" + "\n\n".join(sections)
+
+
+def _skill_section(skills: Sequence[Skill]) -> str:
+    return build_skill_index(list(skills))
+
+
+def _agents_md_search_paths(cwd: str) -> list[Path]:
+    """Return ``AGENTS.md`` search paths in lowest-to-highest precedence order."""
+    from rlmagent.discovery import default_paths
+
+    paths = default_paths(project=Path(cwd))
+    user = [
+        paths.home / _AGENTS_FILE,                  # ~/.rlm-agent/AGENTS.md
+        paths.agents_home / _AGENTS_FILE,            # ~/.agents/AGENTS.md
+    ]
+    if not paths.project_enabled:
+        return user
+    return [
+        *user,
+        paths.project / ".rlm-agent" / _AGENTS_FILE,     # <project>/.rlm-agent/AGENTS.md
+        paths.project / ".agents" / _AGENTS_FILE,    # <project>/.agents/AGENTS.md
+        paths.project / _AGENTS_FILE,                # <project>/AGENTS.md (highest)
+    ]
+
+
+def _read_agents_file(path: Path) -> str:
+    """Read and return the trimmed contents of an AGENTS.md, or empty string."""
+    if not path.is_file():
+        return ""
+    try:
+        return path.read_text(encoding="utf-8").strip()
+    except OSError:
+        return ""
+
+
+def _project_sections(cwd: str) -> list[PromptSection]:
+    """One section per ``AGENTS.md`` found, in precedence order."""
+    found = [
+        (path, content)
+        for path in _agents_md_search_paths(cwd)
+        if (content := _read_agents_file(path))
+    ]
+    sections: list[PromptSection] = []
+    for index, (path, content) in enumerate(found):
+        text = content
+        if index == 0:
+            text = f"## Project instructions ({_AGENTS_FILE})\n\n{content}"
+        sections.append(PromptSection("Project instructions", str(path), text))
+    return sections
+
+
+def _project_context(cwd: str) -> str:
+    """Collect project instructions from ``AGENTS.md`` across the precedence hierarchy."""
+    return "\n\n".join(section.text for section in _project_sections(cwd))
+
+
+def _environment_suffix(cwd: str, *, include_date: bool) -> str:
+    lines = [f"Working directory: {cwd}"]
+    if include_date:
+        lines.append(f"Current date: {datetime.now(UTC):%Y-%m-%d}")
+    return "\n".join(lines)
+
+
+@dataclass(frozen=True, slots=True)
+class PromptSection:
+    """One contiguous piece of the system prompt and where it came from."""
+
+    title: str
+    origin: str
+    text: str
+
+
+def prompt_sections(
+    *,
+    tools: Sequence[ToolSpec] = (),
+    skills: Sequence[Skill] = (),
+    cwd: str | None = None,
+    include_date: bool = True,
+    identity: str | None = None,
+    project: bool = True,
+) -> list[PromptSection]:
+    """The system prompt as attributed sections, in the order they are sent."""
+    resolved_cwd = cwd or os.getcwd()
+    tool_text = _tool_guidelines(tools)
+    skill_text = _skill_section(skills)
+    sections = [PromptSection("Identity", "built-in", identity or _BASE_IDENTITY)]
+    if tool_text:
+        names = ", ".join(t.name for t in tools if t.prompt_snippet or t.prompt_guidelines)
+        sections.append(PromptSection("Tool guidelines", f"tools: {names}", tool_text))
+    if skill_text:
+        sections.append(PromptSection("Skills", f"{len(skills)} loaded skill(s)", skill_text))
+    if project:
+        sections += _project_sections(resolved_cwd)
+    sections.append(PromptSection(
+        "Environment",
+        "working directory" + (" and date" if include_date else ""),
+        _environment_suffix(resolved_cwd, include_date=include_date),
+    ))
+    return sections
+
+
+def system_prompt(
+    *,
+    tools: Sequence[ToolSpec] = (),
+    skills: Sequence[Skill] = (),
+    cwd: str | None = None,
+    include_date: bool = True,
+    identity: str | None = None,
+    project: bool = True,
+) -> str:
+    """Assemble the full system prompt: identity, tool guidance, skills, project context, env."""
+    sections = prompt_sections(
+        tools=tools, skills=skills, cwd=cwd, include_date=include_date,
+        identity=identity, project=project,
+    )
+    return "\n\n".join(section.text for section in sections)
+
+
+__all__ = ["PromptSection", "prompt_sections", "system_prompt"]