rlmness-cli 0.2.0__py3-none-any.whl

rlmagent/playbook/store.py

@@ -0,0 +1,67 @@
+"""Playbook entries and their JSON file."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+KINDS = ("rule", "memory", "skill", "role")
+
+
+@dataclass
+class Entry:
+    id: str
+    kind: str
+    title: str
+    content: str
+    scope: str
+    callable: str | None = None
+    version: int = 1
+    updated: float = field(default_factory=time.time)
+    #: Dropped this many finished tasks after `made_at_task`. None keeps it for good.
+    expires_after_tasks: int | None = None
+    made_at_task: int = 0
+
+
+@dataclass
+class Playbook:
+    entries: dict[str, Entry] = field(default_factory=dict)
+    history: list[dict] = field(default_factory=list)
+    tasks: int = 0
+
+
+def load(path: Path | None) -> Playbook:
+    if path is None:
+        return Playbook()
+    try:
+        doc = json.loads(Path(path).read_text(encoding="utf-8"))
+        entries = {e["id"]: Entry(**e) for e in doc.get("entries", [])}
+        return Playbook(entries=entries, history=list(doc.get("history", [])),
+                        tasks=int(doc.get("tasks", 0)))
+    except (OSError, ValueError, TypeError, KeyError):
+        return Playbook()
+
+
+def save(path: Path | None, pb: Playbook) -> None:
+    if path is None:
+        return
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    doc = {"entries": [asdict(e) for e in pb.entries.values()], "history": pb.history,
+           "tasks": pb.tasks}
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(doc, indent=1), encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def merged(local: Playbook, shared: Playbook) -> list[Entry]:
+    """Shared entries plus local ones; a local id that clashes is shown as `local:<id>`."""
+    out = list(shared.entries.values())
+    for entry in local.entries.values():
+        if entry.id in shared.entries:
+            entry = Entry(**{**asdict(entry), "id": f"local:{entry.id}"})
+        out.append(entry)
+    return out

rlmagent/plugins.py

@@ -0,0 +1,327 @@
+"""Local extensions: file-based discovery, dynamic import, and hot reload."""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass
+from importlib import invalidate_caches
+from importlib.util import module_from_spec, spec_from_file_location
+from pathlib import Path
+from types import ModuleType
+
+RLM_AGENT_HOME_ENV = "RLM_AGENT_HOME"
+EXTENSIONS_DIR_ENV = "RLM_AGENT_EXTENSIONS_DIR"
+
+#: Attribute an extension module must expose: a zero-arg callable.
+ENTRY_ATTRIBUTE = "register"
+
+#: Prefix for synthetic module names, so extensions never collide with real packages.
+_MODULE_PREFIX = "rlm_agent_ext_"
+
+#: Module names this process has imported as extensions (used by unload).
+_imported: set[str] = set()
+
+
+# ---------------------------------------------------------------------------
+# Results
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class LoadedExtension:
+    """A successfully imported and registered extension."""
+
+    name: str
+    path: Path
+    module: ModuleType
+    value: object | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ExtensionFailure:
+    """An extension that could not be imported or registered."""
+
+    name: str
+    path: Path
+    error: str
+
+
+@dataclass(frozen=True, slots=True)
+class LoadResult:
+    """Outcome of one discovery + load pass."""
+
+    loaded: tuple[LoadedExtension, ...] = ()
+    failures: tuple[ExtensionFailure, ...] = ()
+    searched: tuple[Path, ...] = ()
+
+    @property
+    def count(self) -> int:
+        """Number of extensions successfully loaded."""
+        return len(self.loaded)
+
+
+# ---------------------------------------------------------------------------
+# Paths
+# ---------------------------------------------------------------------------
+
+
+def rlm_agent_home() -> Path:
+    """Return the rlm-agent home directory (``$RLM_AGENT_HOME`` or ``~/.rlm-agent``)."""
+    from rlmagent.discovery import default_paths
+
+    return default_paths().home
+
+
+def extension_dirs(
+    *,
+    project_dir: Path | str | None = None,
+    include_project: bool = True,
+    extra: tuple[Path | str, ...] = (),
+) -> tuple[Path, ...]:
+    """Return the extension search directories, in precedence order."""
+    dirs: list[Path] = []
+
+    override = os.environ.get(EXTENSIONS_DIR_ENV)
+    dirs.append(Path(override) if override else rlm_agent_home() / "extensions")
+
+    if include_project:
+        from rlmagent.trust import project_inputs_allowed
+
+        root = Path(project_dir) if project_dir is not None else Path.cwd()
+        # Project plugins run as code, so an untrusted folder never gets them.
+        if project_inputs_allowed(root):
+            dirs.append(root / ".rlm-agent" / "extensions")
+
+    dirs.extend(Path(path) for path in extra)
+    return tuple(dirs)
+
+
+# ---------------------------------------------------------------------------
+# Discovery
+# ---------------------------------------------------------------------------
+
+
+def _is_hidden(name: str) -> bool:
+    return name.startswith("_") or name.startswith(".")
+
+
+def discover_extension_files(dirs: tuple[Path, ...]) -> tuple[tuple[str, Path], ...]:
+    """Find ``(name, path)`` pairs for every extension in *dirs*."""
+    found: dict[str, Path] = {}
+
+    for directory in dirs:
+        if not directory.is_dir():
+            continue
+        for entry in sorted(directory.iterdir()):
+            if _is_hidden(entry.name):
+                continue
+            if entry.is_file() and entry.suffix == ".py":
+                found[entry.stem] = entry
+            elif entry.is_dir():
+                candidate = entry / "extension.py"
+                if candidate.is_file():
+                    found[entry.name] = candidate
+
+    return tuple(found.items())
+
+
+# ---------------------------------------------------------------------------
+# Loading
+# ---------------------------------------------------------------------------
+
+
+def _import_module(name: str, path: Path) -> ModuleType:
+    """Import *path* as a module under a synthetic, collision-free name."""
+    module_name = f"{_MODULE_PREFIX}{name}"
+
+    # A package-style extension (dir/extension.py) needs its directory on the
+    # search path so sibling relative imports resolve.
+    search_locations = [str(path.parent)] if path.name == "extension.py" else None
+
+    spec = spec_from_file_location(
+        module_name, path, submodule_search_locations=search_locations
+    )
+    if spec is None:
+        raise ImportError(f"cannot build a module spec for {path}")
+
+    module = module_from_spec(spec)
+    sys.modules[module_name] = module
+    try:
+        code = compile(path.read_text(encoding="utf-8"), str(path), "exec")
+        exec(code, module.__dict__)  # noqa: S102 - extensions are code by design
+    except BaseException:
+        sys.modules.pop(module_name, None)
+        raise
+    _imported.add(module_name)
+    return module
+
+
+def load_extensions(
+    *,
+    project_dir: Path | str | None = None,
+    include_project: bool = True,
+    extra: tuple[Path | str, ...] = (),
+) -> LoadResult:
+    """Discover, import, and register every extension found on disk."""
+    dirs = extension_dirs(
+        project_dir=project_dir, include_project=include_project, extra=extra
+    )
+    loaded: list[LoadedExtension] = []
+    failures: list[ExtensionFailure] = []
+
+    for name, path in discover_extension_files(dirs):
+        try:
+            module = _import_module(name, path)
+        except BaseException as exc:  # noqa: BLE001 - extensions are untrusted
+            failures.append(ExtensionFailure(name=name, path=path, error=str(exc)))
+            continue
+
+        entry = getattr(module, ENTRY_ATTRIBUTE, None)
+        if entry is None:
+            failures.append(
+                ExtensionFailure(
+                    name=name,
+                    path=path,
+                    error=f"no {ENTRY_ATTRIBUTE}() found in {path.name}",
+                )
+            )
+            continue
+        if not callable(entry):
+            failures.append(
+                ExtensionFailure(
+                    name=name, path=path, error=f"{ENTRY_ATTRIBUTE} is not callable"
+                )
+            )
+            continue
+
+        try:
+            value = entry()
+        except BaseException as exc:  # noqa: BLE001 - extensions are untrusted
+            failures.append(
+                ExtensionFailure(
+                    name=name, path=path, error=f"{ENTRY_ATTRIBUTE}() raised: {exc}"
+                )
+            )
+            continue
+
+        loaded.append(
+            LoadedExtension(name=name, path=path, module=module, value=value)
+        )
+
+    return LoadResult(
+        loaded=tuple(loaded), failures=tuple(failures), searched=dirs
+    )
+
+
+# ---------------------------------------------------------------------------
+# Reload
+# ---------------------------------------------------------------------------
+
+
+def contributions(result: LoadResult) -> tuple[list, dict]:
+    """What the loaded extensions offer: tool definitions, and functions by name.
+
+    `register()` may return a ToolSpec, a mapping of name to function, or a list
+    of either. Anything else is left alone, since returning nothing is normal.
+    """
+    from rlmagent.harness.contracts.tooling import ToolSpec
+
+    tools: list = []
+    functions: dict = {}
+    for extension in result.loaded:
+        values = extension.value if isinstance(extension.value, (list, tuple)) else [extension.value]
+        for value in values:
+            if isinstance(value, ToolSpec):
+                tools.append(value)
+            elif isinstance(value, dict):
+                functions.update({
+                    name: fn for name, fn in value.items()
+                    if str(name).isidentifier() and callable(fn)
+                })
+    return tools, functions
+
+
+def as_host_function(fn):
+    """The function a cell calls, always a coroutine and named for its errors."""
+    import inspect
+    from functools import wraps
+
+    if inspect.iscoroutinefunction(fn):
+        return fn
+
+    @wraps(fn)
+    async def call(*args, **kwargs):
+        return fn(*args, **kwargs)
+
+    return call
+
+
+def as_tool(name: str, fn):
+    """An extension function as a tool, for the engine that offers tools to the model."""
+    import inspect
+    import json
+
+    from rlmagent.harness.contracts.tooling import ToolOutcome, ToolSpec
+
+    bound = as_host_function(fn)
+
+    async def run(_call_id, arguments, _signal=None, _on_update=None):
+        value = await bound(**arguments)
+        text = value if isinstance(value, str) else json.dumps(value, default=str)
+        return ToolOutcome(content=text)
+
+    parameters = inspect.signature(fn).parameters
+    return ToolSpec(
+        name=name, label=name, description=inspect.getdoc(fn) or name,
+        parameters={
+            "type": "object",
+            "properties": {key: {} for key in parameters},
+            "required": [key for key, value in parameters.items()
+                         if value.default is inspect.Parameter.empty],
+        },
+        run=run,
+    )
+
+
+def unload_extensions() -> int:
+    """Drop every previously imported extension from ``sys.modules``."""
+    removed = 0
+    for module_name in tuple(_imported):
+        if sys.modules.pop(module_name, None) is not None:
+            removed += 1
+        _imported.discard(module_name)
+    invalidate_caches()
+    return removed
+
+
+def reload_extensions(
+    *,
+    project_dir: Path | str | None = None,
+    include_project: bool = True,
+    extra: tuple[Path | str, ...] = (),
+) -> LoadResult:
+    """Unload, then re-discover and re-import — picks up newly written files."""
+    unload_extensions()
+    return load_extensions(
+        project_dir=project_dir, include_project=include_project, extra=extra
+    )
+
+
+__all__ = [
+    "RLM_AGENT_HOME_ENV",
+    "ENTRY_ATTRIBUTE",
+    "EXTENSIONS_DIR_ENV",
+    "ExtensionFailure",
+    "as_host_function",
+    "as_tool",
+    "contributions",
+    "LoadResult",
+    "LoadedExtension",
+    "rlm_agent_home",
+    "discover_extension_files",
+    "extension_dirs",
+    "load_extensions",
+    "reload_extensions",
+    "unload_extensions",
+]

rlmagent/policy.py

@@ -0,0 +1,105 @@
+"""Run policy: limits and guards set for a session, from the command line or a contract."""
+
+from __future__ import annotations
+
+import re
+import shlex
+from dataclasses import dataclass, field
+from urllib.parse import urlparse
+
+DEFAULT_OUTPUT_BYTES = 20_000
+
+
+@dataclass
+class Policy:
+    allow_git: bool = True
+    max_tool_output_bytes: int = DEFAULT_OUTPUT_BYTES  # zero disables this output cap
+    max_compactions: int | None = None
+    agent_max_tokens: int | None = None  # completion tokens one agent may spend
+    search_block: list[str] = field(default_factory=list)
+    shell_access: str = "workspace"
+    shell_network: bool = False
+    allowed_tools: frozenset[str] | None = None
+
+    def allows_tool(self, name: str) -> bool:
+        return self.allowed_tools is None or name in self.allowed_tools
+
+
+# Git commands that only look at or change the current branch's working state.
+_GIT_LOCAL = {
+    "status", "diff", "add", "commit", "restore", "rm", "mv", "show", "log", "blame",
+    "stash", "apply", "grep", "ls-files", "rev-parse", "describe", "shortlog", "mergetool",
+}
+# Subcommands that touch other refs, other branches, remotes or history.
+_GIT_REACHING = {
+    "push", "pull", "fetch", "clone", "remote", "checkout", "switch", "branch", "tag",
+    "merge", "rebase", "reset", "cherry-pick", "revert", "worktree", "reflog", "gc",
+    "filter-branch", "update-ref", "symbolic-ref", "for-each-ref", "notes", "submodule",
+    "bisect", "replace", "prune", "am", "format-patch", "send-email", "config",
+}
+
+
+def _git_calls(command: str):
+    """The git subcommands in a shell line, split on ; && || | and newlines."""
+    for piece in re.split(r"&&|\|\||[;|\n]", command):
+        try:
+            words = shlex.split(piece, posix=True)
+        except ValueError:
+            words = piece.split()
+        while words and "=" in words[0] and not words[0].startswith("-"):
+            words = words[1:]  # leading VAR=value assignments
+        if not words or words[0].rsplit("/", 1)[-1] not in ("git", "git.exe"):
+            continue
+        rest = words[1:]
+        while rest and rest[0].startswith("-"):
+            # -C dir and -c key=value take a value; other options stand alone.
+            rest = rest[2:] if rest[0] in ("-C", "-c") else rest[1:]
+        yield (rest[0] if rest else ""), rest[1:]
+
+
+def git_refusal(command: str, policy: Policy) -> str | None:
+    """Why a shell command may not run under this policy, or None."""
+    if policy.allow_git:
+        return None
+    for sub, args in _git_calls(command):
+        if sub in _GIT_REACHING:
+            return (f"git {sub} touches other branches, remotes or history, which this run does not allow; "
+                    "run; work with status, diff, add, commit and log")
+        if sub == "log" and any(a in ("--all", "--branches", "--remotes", "--tags") for a in args):
+            return "git log over other refs is turned off for this run"
+        if sub not in _GIT_LOCAL and sub:
+            return f"git {sub} is not on this run's list of allowed git commands"
+    return None
+
+
+def cap_output(text: str, limit: int) -> str:
+    """Keep the start and end of long output, saying how much was left out."""
+    data = text.encode("utf-8", errors="replace")
+    if limit <= 0 or len(data) <= limit:
+        return text
+    head = data[: limit * 2 // 3].decode("utf-8", errors="ignore")
+    tail = data[-(limit // 3):].decode("utf-8", errors="ignore")
+    cut = len(data) - len(head.encode()) - len(tail.encode())
+    return (f"{head}\n... [{cut} bytes of output left out; print less, or slice what you "
+            f"need] ...\n{tail}")
+
+
+def blocked_url(url: str, policy: Policy) -> bool:
+    """Whether a URL is on the run's block list (a domain, *.domain, or an origin)."""
+    parsed = urlparse(url)
+    host = (parsed.hostname or "").lower()
+    origin = f"{parsed.scheme}://{parsed.netloc}".lower()
+    for rule in policy.search_block:
+        rule = rule.lower().rstrip("/")
+        if "://" in rule:
+            if origin == rule:
+                return True
+        elif rule.startswith("*."):
+            if host.endswith(rule[1:]):
+                return True
+        elif host == rule or host.endswith("." + rule):
+            return True
+    return False
+
+
+__all__ = ["DEFAULT_OUTPUT_BYTES", "Policy", "blocked_url", "cap_output", "git_refusal"]

rlmagent/prompt_refs.py

@@ -0,0 +1,57 @@
+"""Files and links a prompt mentions, loaded before the turn so the agent starts with them."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+MAX_FILES = 10
+MAX_BYTES = 200_000
+
+_LINK = re.compile(r"https?://[^\s)>\]'\"`]+")
+_CANDIDATES = (
+    re.compile(r"`([^`\n]+)`"),          # `path`
+    re.compile(r"@([^\s,;]+)"),            # @path
+    re.compile(r"\]\(([^)\s]+)\)"),        # [text](path)
+    re.compile(r"(?<![\w/.@])((?:[\w.-]+[/\\])*[\w.-]+\.\w{1,8})(?![\w/])"),  # plain a/b.py
+)
+
+
+def _inside(path: Path, root: Path) -> bool:
+    return path == root or root in path.parents
+
+
+def references(text: str, root: str | Path) -> dict:
+    """`{"prompt", "links", "files": [{"path", "content"}]}`; missing, binary, large and
+    outside-the-workspace files are left out."""
+    root = Path(root).resolve()
+    links = list(dict.fromkeys(m.rstrip(".,;:!?)]}") for m in _LINK.findall(text)))
+    bare = [word.strip("`\"'()[]{}<>,;:!?@") for word in text.split()]
+    seen, files = set(), []
+    for raw in [found for pattern in _CANDIDATES for found in pattern.findall(text)] + bare:
+        raw = raw.strip().rstrip(".,:;")
+        if not raw or raw.startswith(("http://", "https://")) or len(files) >= MAX_FILES:
+            continue
+        path = (root / raw).resolve()
+        if path in seen or not _inside(path, root) or not path.is_file():
+            continue
+        seen.add(path)
+        if path.stat().st_size > MAX_BYTES:
+            continue
+        try:
+            content = path.read_text(encoding="utf-8")
+        except (UnicodeDecodeError, OSError):
+            continue
+        files.append({"path": path.relative_to(root).as_posix(), "content": content})
+    return {"prompt": text, "links": links, "files": files}
+
+
+def note(refs: dict) -> str:
+    """The line added to the prompt so the agent knows what is waiting in its kernel."""
+    parts = []
+    if refs["files"]:
+        parts.append("PROMPT['files'] is a list of {'path', 'content'} dicts for "
+                     + ", ".join(f["path"] for f in refs["files"]))
+    if refs["links"]:
+        parts.append("PROMPT['links'] holds the links")
+    return f"\n\n[Preloaded in the python kernel: {'; '.join(parts)}.]" if parts else ""