rlmness-cli 0.2.0__py3-none-any.whl

rlmagent/shell_sandbox.py

@@ -0,0 +1,88 @@
+"""Build a shell with a private filesystem and an explicit workspace mount."""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from functools import lru_cache
+from pathlib import Path
+
+from rlmness.environment import execution_environment
+
+_SUPERVISE = """
+import json, os, signal, subprocess, sys, threading
+child = subprocess.Popen(json.loads(sys.argv[1]), stdin=subprocess.DEVNULL, start_new_session=True)
+def stop():
+    try: os.killpg(child.pid, signal.SIGKILL)
+    except ProcessLookupError: pass
+def watch():
+    while os.read(0, 4096): pass
+    stop()
+threading.Thread(target=watch, daemon=True).start()
+try: code = child.wait()
+finally: stop()
+raise SystemExit(code if code >= 0 else 128-code)
+"""
+
+
+class SandboxUnavailable(OSError):
+    pass
+
+
+@lru_cache(maxsize=1)
+def _runner():
+    if os.name == "nt":
+        wsl = Path(os.environ.get("SystemRoot", "C:/Windows")) / "System32/wsl.exe"
+        prefix = [str(wsl), "--exec"]
+        probe = prefix + ["/usr/bin/bwrap", "--version"]
+    elif sys.platform.startswith("linux"):
+        bwrap = shutil.which("bwrap")
+        if bwrap is None:
+            raise SandboxUnavailable("Install Bubblewrap for workspace-isolated shell execution")
+        prefix, probe = [], [bwrap, "--version"]
+    else:
+        raise SandboxUnavailable("Workspace shell isolation requires Linux/Bubblewrap or WSL")
+    try:
+        answer = subprocess.run(probe, capture_output=True, timeout=30,
+                                env=execution_environment())
+    except (OSError, subprocess.TimeoutExpired) as error:
+        raise SandboxUnavailable("Workspace shell isolation is unavailable; configure Bubblewrap "
+                                 "in Linux/WSL or explicitly grant --shell-access host") from error
+    if answer.returncode:
+        raise SandboxUnavailable("Bubblewrap is unavailable in the selected Linux/WSL environment; "
+                                 "install it or explicitly grant --shell-access host")
+    return prefix, probe[len(prefix)]
+
+
+def plan(cwd, command, *, argv=None, env=None, network=False):
+    """Return a supervised argv. Keep its stdin pipe open for its entire lifetime."""
+    prefix, bwrap = _runner()
+    workspace = str(Path(cwd).resolve())
+    if prefix:
+        mapped = subprocess.run(prefix + ["/usr/bin/wslpath", "-a", "-u", workspace],
+            capture_output=True, text=True, encoding="utf-8", timeout=15,
+            env=execution_environment())
+        if mapped.returncode or not mapped.stdout.strip().startswith("/"):
+            raise SandboxUnavailable("WSL could not resolve the workspace mount")
+        workspace = mapped.stdout.strip()
+    options = [bwrap, "--die-with-parent", "--new-session", "--unshare-user",
+        "--unshare-pid", "--unshare-ipc", "--unshare-uts", "--cap-drop", "ALL",
+        "--ro-bind", "/usr", "/usr", "--ro-bind", "/bin", "/bin",
+        "--ro-bind", "/lib", "/lib", "--ro-bind-try", "/lib64", "/lib64",
+        "--proc", "/proc", "--dev", "/dev", "--tmpfs", "/tmp", "--dir", "/tmp/home",
+        "--bind", workspace, "/workspace", "--chdir", "/workspace", "--clearenv"]
+    if not network:
+        options += ["--unshare-net"]
+    else:
+        for name in ("resolv.conf", "hosts", "nsswitch.conf"):
+            options += ["--ro-bind-try", "/etc/" + name, "/etc/" + name]
+        options += ["--ro-bind-try", "/etc/ssl/certs", "/etc/ssl/certs"]
+    variables = {"PATH": "/usr/local/bin:/usr/bin:/bin", "HOME": "/tmp/home",
+        "LANG": "C.UTF-8", "PYTHONIOENCODING": "utf-8", "PYTHONUTF8": "1", **(env or {})}
+    for key, value in variables.items():
+        if value is not None:
+            options += ["--setenv", str(key), str(value)]
+    options += ["--", *(argv or ["/bin/bash", "--noprofile", "--norc", "-c", command])]
+    return [*prefix, "/usr/bin/python3", "-I", "-c", _SUPERVISE, json.dumps(options)]

rlmagent/skillset.py

@@ -0,0 +1,320 @@
+"""Markdown-based skill system: discovery, loading, expansion, and indexing."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+# ── constants ──────────────────────────────────────────────────────────────
+
+_SKILL_FILE = "SKILL.md"
+_AGENTS_FILE = "AGENTS.md"
+_FRONT_MATTER_FENCE = "---"
+_COMMAND_PREFIX = "/skill:"
+_INVOCATION_TAG = "skill-invocation"
+
+
+# ── diagnostic levels ─────────────────────────────────────────────────────
+
+
+class Severity(Enum):
+    """Non-fatal diagnostic severity."""
+
+    INFO = "info"
+    WARNING = "warning"
+
+
+# ── data models ────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class Skill:
+    """An immutable, loaded skill definition."""
+
+    name: str
+    description: str
+    body: str
+    source: Path
+
+    @property
+    def command(self) -> str:
+        """The slash command that invokes this skill."""
+        return f"{_COMMAND_PREFIX}{self.name}"
+
+
+@dataclass(frozen=True, slots=True)
+class SkillInvocation:
+    """A parsed ``/skill:<name>`` expansion ready for prompt injection."""
+
+    name: str
+    arguments: str
+    body: str
+
+
+@dataclass(frozen=True, slots=True)
+class SkillDiagnostic:
+    """A non-fatal issue encountered during skill discovery."""
+
+    severity: Severity
+    path: Path
+    message: str
+
+
+class SkillLoadError(Exception):
+    """Fatal error during skill loading (unreadable file, bad encoding)."""
+
+
+# ── front-matter parsing ──────────────────────────────────────────────────
+
+_FRONT_MATTER_RE = re.compile(
+    r"\A---[ \t]*\n(.*?\n)---[ \t]*\n",
+    re.DOTALL,
+)
+
+
+def _parse_front_matter(text: str) -> tuple[dict[str, str], str]:
+    """Split optional YAML front matter from the markdown body."""
+    match = _FRONT_MATTER_RE.match(text)
+    if match is None:
+        return {}, text
+
+    raw_yaml = match.group(1)
+    body = text[match.end():]
+    meta: dict[str, str] = {}
+    for line in raw_yaml.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        colon = line.find(":")
+        if colon < 1:
+            continue
+        key = line[:colon].strip()
+        value = line[colon + 1:].strip()
+        # Strip surrounding quotes
+        if len(value) >= 2 and value[0] in ('"', "'") and value[-1] == value[0]:
+            value = value[1:-1]
+        meta[key] = value
+
+    return meta, body
+
+
+def _derive_description(body: str) -> str:
+    """Extract the first non-heading, non-empty paragraph as a description."""
+    for line in body.splitlines():
+        stripped = line.strip()
+        if not stripped:
+            continue
+        if stripped.startswith("#"):
+            continue
+        if stripped.startswith("---"):
+            continue
+        return stripped
+    return ""
+
+
+# ── single-skill loading ──────────────────────────────────────────────────
+
+
+def _load_skill_from_dir(skill_dir: Path) -> Skill:
+    """Read ``SKILL.md`` from *skill_dir* and return a ``Skill``."""
+    md_path = skill_dir / _SKILL_FILE
+    try:
+        raw = md_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise SkillLoadError(f"Cannot read {md_path}: {exc}") from exc
+    except UnicodeDecodeError as exc:
+        raise SkillLoadError(
+            f"{md_path} is not valid UTF-8: {exc}"
+        ) from exc
+
+    meta, body = _parse_front_matter(raw)
+    name = meta.get("name", skill_dir.name)
+    description = meta.get("description", "") or _derive_description(body)
+
+    return Skill(
+        name=name,
+        description=description,
+        body=body,
+        source=md_path,
+    )
+
+
+# ── multi-directory discovery ─────────────────────────────────────────────
+
+
+def _discover_in_directory(
+    root: Path,
+) -> tuple[list[Skill], list[SkillDiagnostic]]:
+    """Scan a single resource directory for skills."""
+    skills: list[Skill] = []
+    diagnostics: list[SkillDiagnostic] = []
+    seen_names: dict[str, Path] = {}
+
+    if not root.is_dir():
+        return skills, diagnostics
+
+    for child in sorted(root.iterdir()):
+        # Skip AGENTS.md
+        if child.name == _AGENTS_FILE:
+            continue
+
+        # Bare .md files are not skills
+        if child.is_file() and child.suffix.lower() == ".md":
+            diagnostics.append(SkillDiagnostic(
+                severity=Severity.INFO,
+                path=child,
+                message=(
+                    f"Bare markdown file ignored. To make it a skill, "
+                    f"move it to {child.stem}/{_SKILL_FILE}"
+                ),
+            ))
+            continue
+
+        # Only directories with SKILL.md
+        if not child.is_dir():
+            continue
+        if not (child / _SKILL_FILE).is_file():
+            continue
+
+        try:
+            skill = _load_skill_from_dir(child)
+        except SkillLoadError as exc:
+            diagnostics.append(SkillDiagnostic(
+                severity=Severity.WARNING,
+                path=child,
+                message=str(exc),
+            ))
+            continue
+
+        if skill.name in seen_names:
+            diagnostics.append(SkillDiagnostic(
+                severity=Severity.WARNING,
+                path=child,
+                message=(
+                    f"Duplicate skill name {skill.name!r} in same directory; "
+                    f"already defined at {seen_names[skill.name]}"
+                ),
+            ))
+            continue
+
+        seen_names[skill.name] = child
+        skills.append(skill)
+
+    return skills, diagnostics
+
+
+def load_skills_with_diagnostics(
+    resource_dirs: Sequence[Path],
+) -> tuple[list[Skill], list[SkillDiagnostic]]:
+    """Load skills from multiple resource directories with diagnostics."""
+    combined: dict[str, Skill] = {}
+    all_diagnostics: list[SkillDiagnostic] = []
+
+    for root in resource_dirs:
+        skills, diags = _discover_in_directory(root)
+        all_diagnostics.extend(diags)
+        for skill in skills:
+            if skill.name not in combined:
+                combined[skill.name] = skill
+
+    return list(combined.values()), all_diagnostics
+
+
+def load_skills(resource_dirs: Sequence[Path]) -> list[Skill]:
+    """Load skills from resource directories, discarding diagnostics."""
+    skills, _ = load_skills_with_diagnostics(resource_dirs)
+    return skills
+
+
+# ── command expansion ──────────────────────────────────────────────────────
+
+
+def expand_command(
+    text: str,
+    skills: dict[str, Skill],
+) -> str | None:
+    """Expand a ``/skill:<name>`` command into an XML invocation block."""
+    if not text.startswith(_COMMAND_PREFIX):
+        return None
+
+    rest = text[len(_COMMAND_PREFIX):]
+    parts = rest.split(None, 1)
+    name = parts[0] if parts else rest
+    arguments = parts[1] if len(parts) > 1 else ""
+
+    if name not in skills:
+        raise KeyError(f"Unknown skill: {name!r}")
+
+    skill = skills[name]
+    return format_invocation(SkillInvocation(
+        name=name,
+        arguments=arguments,
+        body=skill.body,
+    ))
+
+
+# ── invocation formatting / parsing ────────────────────────────────────────
+
+_INVOCATION_RE = re.compile(
+    rf"<{_INVOCATION_TAG}\s+name=\"([^\"]+)\"(?:\s+arguments=\"([^\"]*)\")?>\n"
+    rf"(.*?)"
+    rf"</{_INVOCATION_TAG}>",
+    re.DOTALL,
+)
+
+
+def format_invocation(invocation: SkillInvocation) -> str:
+    """Render a ``SkillInvocation`` as an XML-like block."""
+    attrs = f'name="{invocation.name}"'
+    if invocation.arguments:
+        attrs += f' arguments="{invocation.arguments}"'
+    return (
+        f"<{_INVOCATION_TAG} {attrs}>\n"
+        f"{invocation.body}\n"
+        f"</{_INVOCATION_TAG}>"
+    )
+
+
+def parse_invocation(text: str) -> SkillInvocation | None:
+    """Parse an XML-like skill invocation block back into a ``SkillInvocation``."""
+    match = _INVOCATION_RE.search(text)
+    if match is None:
+        return None
+    return SkillInvocation(
+        name=match.group(1),
+        arguments=match.group(2) or "",
+        body=match.group(3).strip(),
+    )
+
+
+# ── skill index for system prompts ────────────────────────────────────────
+
+
+def build_skill_index(skills: Sequence[Skill]) -> str:
+    """Build a concise skill listing suitable for inclusion in a system prompt."""
+    if not skills:
+        return ""
+    lines = [
+        f"  {skill.command} — {skill.description}"
+        for skill in sorted(skills, key=lambda s: s.name)
+    ]
+    header = "Available skills (invoke with /skill:<name>):"
+    return header + "\n" + "\n".join(lines)
+
+
+__all__ = [
+    "Severity",
+    "Skill",
+    "SkillDiagnostic",
+    "SkillInvocation",
+    "SkillLoadError",
+    "build_skill_index",
+    "expand_command",
+    "format_invocation",
+    "load_skills",
+    "load_skills_with_diagnostics",
+    "parse_invocation",
+]

rlmagent/steering.py

@@ -0,0 +1,148 @@
+"""Accepted instructions and model-boundary delivery receipts."""
+
+from __future__ import annotations
+
+import copy
+import json
+import threading
+import time
+from pathlib import Path
+from uuid import uuid4
+
+from rlmagent.refinement.store import _lock
+
+
+class Steering:
+    def __init__(self, path: Path | None):
+        self.path = path
+        self.memory = {}
+        self._mutex = threading.RLock()
+
+    def _read(self):
+        if self.path is None:
+            with self._mutex:
+                return copy.deepcopy(self.memory)
+        try:
+            return json.loads(self.path.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            return {}
+
+    def _write(self, records):
+        if self.path is None:
+            with self._mutex:
+                self.memory = records
+            return
+        temporary = self.path.with_suffix(f".{uuid4().hex}.tmp")
+        try:
+            temporary.write_text(json.dumps(records), encoding="utf-8")
+            temporary.replace(self.path)
+        finally:
+            temporary.unlink(missing_ok=True)
+
+    def _guard(self):
+        return self._mutex if self.path is None else _lock(self.path.with_suffix(".lock"))
+
+    def accept(self, text: str, identity: str | None = None, target: str = "root", *,
+               once: bool = False, allow_new: bool = True):
+        identity = identity or uuid4().hex
+        if (
+            not isinstance(identity, str)
+            or not 1 <= len(identity) <= 128
+            or not isinstance(target, str)
+            or not 1 <= len(target) <= 256
+            or not isinstance(text, str)
+            or not text.strip()
+            or len(text) > 65536
+        ):
+            raise ValueError("Invalid steering identity, target or text")
+
+        def update():
+            records = self._read()
+            if identity in records:
+                previous = records[identity]
+                if (previous["text"] != text or previous["target"] != target
+                        or previous.get("once", False) != once):
+                    raise ValueError("messageId was already used with different content or target")
+                return self.receipt(identity, previous)
+            if not allow_new:
+                raise ValueError("child is idle or finished; use send for a follow-up turn")
+            if len(records) >= 10000:
+                raise ValueError("Steering identity limit reached")
+            records[identity] = {
+                "text": text,
+                "target": target,
+                "accepted_at": time.time(),
+                "deliveries": {},
+            }
+            if once:
+                records[identity]["once"] = True
+            self._write(records)
+            return self.receipt(identity, records[identity])
+
+        with self._guard():
+            return update()
+
+    @staticmethod
+    def receipt(identity, record):
+        return {
+            "messageId": identity,
+            "target": record["target"],
+            "status": ("consumed" if record["deliveries"] else
+                       "expired" if "expired_at" in record else "accepted"),
+            "deliveries": dict(record["deliveries"]),
+        }
+
+    def receipts(self, *, target: str | None = None):
+        return [self.receipt(identity, record) for identity, record in self._read().items()
+                if target is None or record["target"] == target]
+
+    def context(self, agent: str, *, root: bool = False, child: str | None = None):
+        targets = {agent}
+        if root:
+            targets.add("root")
+        if child is not None:
+            targets.add(child)
+        instructions, pending = [], []
+        for identity, record in self._read().items():
+            target = record["target"]
+            if target not in targets or "expired_at" in record:
+                continue
+            delivered = (child if target == child else agent) in record["deliveries"]
+            if not delivered or not record.get("once", False):
+                instructions.append(record["text"])
+            if not delivered:
+                pending.append(identity)
+        return "\n\n".join(instructions), pending
+
+    def consumed(self, identities, agent: str, request: str | None, *, child: str | None = None):
+        if not identities:
+            return
+
+        def update():
+            records = self._read()
+            for identity in identities:
+                record = records[identity]
+                record["deliveries"].setdefault(
+                    child if record["target"] == child else agent,
+                    {
+                        "requestId": request,
+                        "consumed_at": time.time(),
+                    },
+                )
+            self._write(records)
+
+        with self._guard():
+            update()
+
+    def expire_child(self, child: str) -> None:
+        """Close undelivered one-shot instructions at the end of a child turn."""
+        with self._guard():
+            records = self._read()
+            pending = [record for record in records.values()
+                       if record["target"] == child and record.get("once")
+                       and not record["deliveries"] and "expired_at" not in record]
+            if pending:
+                finished = time.time()
+                for record in pending:
+                    record["expired_at"] = finished
+                self._write(records)

rlmagent/stops.py

@@ -0,0 +1,62 @@
+"""Why a run stopped, as one word a training or evaluation pipeline can act on.
+
+done              the agent answered
+max_calls         the tree used up its model calls
+max_cost          the tree used up its spend
+max_tokens        the tree used up its completion or prompt tokens
+max_seconds       the run used up its time
+agent_tokens      one agent used up its completion tokens
+compaction_failed the context was full and could not be compacted
+no_answer         the run ended without a usable answer (an empty or failed final reply)
+cancelled         the user or client stopped it
+error             anything else, with the message beside it
+"""
+
+from __future__ import annotations
+
+_LIMITS = (
+    ("calls reaches the limit", "max_calls"),
+    ("cost ", "max_cost"),
+    ("completion tokens", "max_tokens"),
+    ("prompt tokens", "max_tokens"),
+    ("tokens", "max_tokens"),
+    ("s reaches the limit", "max_seconds"),
+)
+
+
+def classify(refusal: str | None, final_text: str, error: str | None,
+             cancelled: bool = False) -> str:
+    if cancelled or (error or "").lower() in ("cancelled", "aborted"):
+        return "cancelled"
+    text = f"{refusal or ''} {error or ''}"
+    if "reached its limit of" in text and "completion tokens" in text:
+        return "agent_tokens"
+    if refusal:
+        for needle, reason in _LIMITS:
+            if needle in refusal:
+                return reason
+        return "max_calls"
+    if "compaction" in (error or "").lower():
+        return "compaction_failed"
+    if error:
+        return "error"
+    if not final_text.strip():
+        return "no_answer"
+    return "done"
+
+
+def of_session(session, refusal: str | None) -> dict:
+    """The stop reason of the session's last turn, with the message that explains it."""
+    last = next((m for m in reversed(list(session.transcript))
+                 if getattr(m, "role", "") == "assistant"), None)
+    text = getattr(last, "text", "") or ""
+    error = getattr(last, "error_message", None)
+    stop = getattr(last, "stop_reason", None)
+    reason = classify(refusal, text, error, cancelled=stop == "aborted")
+    typed = getattr(getattr(session, "backend", None), "last_stop_reason", None)
+    if typed and stop != "aborted":
+        reason = typed
+    return {"stop_reason": reason, "stop_detail": refusal or error or ""}
+
+
+__all__ = ["classify", "of_session"]