rlmness-cli 0.2.0__py3-none-any.whl

rlmagent/discovery.py

@@ -0,0 +1,356 @@
+"""Canonical filesystem layout and automatic resource discovery."""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from rlmagent.harness.contracts.values import JValue
+
+# ---------------------------------------------------------------------------
+# Environment variable names
+# ---------------------------------------------------------------------------
+
+RLM_AGENT_HOME_ENV = "RLM_AGENT_HOME"
+RLM_AGENT_SESSIONS_DIR_ENV = "RLM_AGENT_SESSIONS_DIR"
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+_FRONT_MATTER_RE = re.compile(r"\A---[ \t]*\n(.*?\n)---[ \t]*\n", re.DOTALL)
+
+
+def _resolve_home() -> Path:
+    """Resolve rlm-agent's home directory from ``$RLM_AGENT_HOME`` or ``~/.rlm-agent``."""
+    env = os.environ.get(RLM_AGENT_HOME_ENV)
+    return Path(env) if env else Path.home() / ".rlm-agent"
+
+
+def _resolve_sessions(home: Path) -> Path:
+    """Resolve the sessions directory from ``$RLM_AGENT_SESSIONS_DIR`` or ``<home>/sessions``."""
+    env = os.environ.get(RLM_AGENT_SESSIONS_DIR_ENV)
+    return Path(env) if env else home / "sessions"
+
+
+def _dedupe_paths(paths: list[Path]) -> list[Path]:
+    """Remove duplicate paths while preserving order."""
+    seen: set[Path] = set()
+    result: list[Path] = []
+    for p in paths:
+        resolved = p.resolve()
+        if resolved not in seen:
+            seen.add(resolved)
+            result.append(p)
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Path utility
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class RlmAgentPaths:
+    """Canonical filesystem locations for rlm-agent."""
+
+    home: Path = field(default_factory=_resolve_home)
+    project: Path = field(default_factory=Path.cwd)
+    # False when the project folder is not trusted: search paths then leave
+    # out every project-local location and only user resources load.
+    project_enabled: bool = True
+
+    # ── user home locations ───────────────────────────────────────────
+
+    @property
+    def sessions(self) -> Path:
+        """Session transcript and index storage (``~/.rlm-agent/sessions``)."""
+        return _resolve_sessions(self.home)
+
+    @property
+    def logs(self) -> Path:
+        """Log file directory (``~/.rlm-agent/logs``)."""
+        return self.home / "logs"
+
+    @property
+    def user_skills(self) -> Path:
+        """User-level skill definitions (``~/.rlm-agent/skills``)."""
+        return self.home / "skills"
+
+    @property
+    def user_prompts(self) -> Path:
+        """User-level prompt templates (``~/.rlm-agent/prompts``)."""
+        return self.home / "prompts"
+
+    @property
+    def user_themes(self) -> Path:
+        """User-level theme files (``~/.rlm-agent/themes``)."""
+        return self.home / "themes"
+
+    # ── user .agents locations ────────────────────────────────────────
+
+    @property
+    def agents_home(self) -> Path:
+        """Cross-tool agent resource directory (``~/.agents``)."""
+        return self.home.parent / ".agents"
+
+    @property
+    def agents_skills(self) -> Path:
+        """Cross-tool skill definitions (``~/.agents/skills``)."""
+        return self.agents_home / "skills"
+
+    @property
+    def agents_prompts(self) -> Path:
+        """Cross-tool prompt templates (``~/.agents/prompts``)."""
+        return self.agents_home / "prompts"
+
+    # ── project-local .rlm-agent locations ────────────────────────────────
+
+    @property
+    def project_skills(self) -> Path:
+        """Project-level skill definitions (``<project>/.rlm-agent/skills``)."""
+        return self.project / ".rlm-agent" / "skills"
+
+    @property
+    def project_prompts(self) -> Path:
+        """Project-level prompt templates (``<project>/.rlm-agent/prompts``)."""
+        return self.project / ".rlm-agent" / "prompts"
+
+    @property
+    def project_themes(self) -> Path:
+        """Project-level theme files (``<project>/.rlm-agent/themes``)."""
+        return self.project / ".rlm-agent" / "themes"
+
+    # ── project-local .agents locations ───────────────────────────────
+
+    @property
+    def project_agents(self) -> Path:
+        """Project-level cross-tool agent directory (``<project>/.agents``)."""
+        return self.project / ".agents"
+
+    @property
+    def project_agents_skills(self) -> Path:
+        """Project-level cross-tool skills (``<project>/.agents/skills``)."""
+        return self.project_agents / "skills"
+
+    @property
+    def project_agents_prompts(self) -> Path:
+        """Project-level cross-tool prompts (``<project>/.agents/prompts``)."""
+        return self.project_agents / "prompts"
+
+
+# ---------------------------------------------------------------------------
+# Default instance factory
+# ---------------------------------------------------------------------------
+
+
+def default_paths(
+    *,
+    home: Path | None = None,
+    project: Path | None = None,
+) -> RlmAgentPaths:
+    """Build a ``RlmAgentPaths`` with optional overrides for home and project."""
+    from rlmagent.trust import project_inputs_allowed
+
+    root = project or Path.cwd()
+    return RlmAgentPaths(
+        home=home or _resolve_home(),
+        project=root,
+        project_enabled=project_inputs_allowed(root),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Resource search paths — precedence-ordered directory lists
+# ---------------------------------------------------------------------------
+
+
+def _project_only(paths: RlmAgentPaths, *locations: Path) -> tuple[Path, ...]:
+    """``locations`` when project inputs are enabled, otherwise nothing."""
+    return locations if paths.project_enabled else ()
+
+
+def skill_search_paths(paths: RlmAgentPaths) -> list[Path]:
+    """Return skill directories in highest-precedence-first order."""
+    from rlmagent.packages import resource_dirs
+
+    return _dedupe_paths([
+        *_project_only(paths, paths.project_agents_skills, paths.project_skills),
+        paths.agents_skills,
+        paths.user_skills,
+        *resource_dirs("skills", paths=paths),
+    ])
+
+
+def prompt_search_paths(paths: RlmAgentPaths) -> list[Path]:
+    """Return prompt directories in highest-precedence-first order."""
+    from rlmagent.packages import resource_dirs
+
+    return _dedupe_paths([
+        *_project_only(paths, paths.project_agents_prompts, paths.project_prompts),
+        paths.agents_prompts,
+        paths.user_prompts,
+        *resource_dirs("prompts", paths=paths),
+    ])
+
+
+def theme_search_paths(paths: RlmAgentPaths) -> list[Path]:
+    """Return theme directories in highest-precedence-first order."""
+    from rlmagent.packages import resource_dirs
+
+    return _dedupe_paths([
+        *_project_only(paths, paths.project_themes),
+        paths.user_themes,
+        *resource_dirs("themes", paths=paths),
+    ])
+
+
+def resource_search_paths(
+    paths: RlmAgentPaths,
+    resource_type: str,
+    *,
+    rlm_agent_only: bool = False,
+) -> list[Path]:
+    """Return search directories for an arbitrary resource type."""
+    dirs: list[Path] = []
+    if paths.project_enabled:
+        if not rlm_agent_only:
+            dirs.append(paths.project / ".agents" / resource_type)
+        dirs.append(paths.project / ".rlm-agent" / resource_type)
+    if not rlm_agent_only:
+        dirs.append(paths.agents_home / resource_type)
+    dirs.append(paths.home / resource_type)
+    return _dedupe_paths(dirs)
+
+
+# ---------------------------------------------------------------------------
+# Resource discovery diagnostics
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ResourceDiagnostic:
+    """Non-fatal diagnostic emitted during resource discovery."""
+
+    resource_name: str
+    winner: Path
+    overridden: Path
+    message: str
+
+
+def collect_override_diagnostics(
+    discovered: dict[str, Path],
+    new_resources: dict[str, Path],
+    source_dir: Path,
+) -> list[ResourceDiagnostic]:
+    """Produce diagnostics when resources in *new_resources* would be
+    overridden by existing entries in *discovered*."""
+    diagnostics: list[ResourceDiagnostic] = []
+    for name, new_path in new_resources.items():
+        if name in discovered:
+            diagnostics.append(ResourceDiagnostic(
+                resource_name=name,
+                winner=discovered[name],
+                overridden=new_path,
+                message=(
+                    f"Resource {name!r} from {source_dir} overridden by "
+                    f"higher-precedence copy at {discovered[name]}"
+                ),
+            ))
+    return diagnostics
+
+
+# ---------------------------------------------------------------------------
+# Markdown resource helpers
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class MarkdownResource:
+    """A parsed markdown file with optional frontmatter metadata."""
+
+    path: Path
+    body: str
+    metadata: dict[str, str]
+
+    @property
+    def name(self) -> str:
+        """The ``name`` from frontmatter, or the file/directory stem."""
+        return self.metadata.get("name", self.path.stem)
+
+    @property
+    def description(self) -> str:
+        """The ``description`` from frontmatter, or the first non-heading paragraph."""
+        explicit = self.metadata.get("description")
+        if explicit:
+            return explicit
+        return derive_description(self.body)
+
+    def metadata_json(self) -> dict[str, JValue]:
+        """Return metadata as a JSON-compatible dictionary."""
+        return dict(self.metadata)
+
+
+def parse_front_matter(text: str) -> tuple[dict[str, str], str]:
+    """Split optional YAML-like frontmatter from the markdown body."""
+    match = _FRONT_MATTER_RE.match(text)
+    if match is None:
+        return {}, text
+
+    raw = match.group(1)
+    body = text[match.end():]
+    meta: dict[str, str] = {}
+    for line in raw.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        colon = stripped.find(":")
+        if colon < 1:
+            continue
+        key = stripped[:colon].strip()
+        value = stripped[colon + 1:].strip()
+        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-blank 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 ""
+
+
+def parse_markdown(path: Path) -> MarkdownResource:
+    """Read and parse a markdown file into a ``MarkdownResource``."""
+    raw = path.read_text(encoding="utf-8")
+    metadata, body = parse_front_matter(raw)
+    return MarkdownResource(path=path, body=body, metadata=metadata)
+
+
+__all__ = [
+    "RLM_AGENT_HOME_ENV",
+    "RLM_AGENT_SESSIONS_DIR_ENV",
+    "RlmAgentPaths",
+    "MarkdownResource",
+    "ResourceDiagnostic",
+    "collect_override_diagnostics",
+    "default_paths",
+    "derive_description",
+    "parse_front_matter",
+    "parse_markdown",
+    "prompt_search_paths",
+    "resource_search_paths",
+    "skill_search_paths",
+    "theme_search_paths",
+]

rlmagent/execution_log.py

@@ -0,0 +1,66 @@
+"""Portable step records for execution-log viewers."""
+
+from datetime import UTC, datetime
+
+
+def records(event, history):
+    kind = event["kind"]
+    mapping = {
+        "run_started": "agent_start",
+        "run_failed": "agent_end",
+        "run_completed": "agent_end",
+        "code_generated": "code_generated",
+        "step": "execution_result",
+    }
+    if kind not in mapping:
+        return []
+    agent = event.get("run_id", "root")
+    start = next(
+        (r for r in reversed(history) if r["kind"] == "run_started" and r.get("run_id") == agent),
+        {},
+    )
+    row = {
+        "level": 30,
+        "time": datetime.fromtimestamp(event["timestamp"], UTC).isoformat(),
+        "event_type": mapping[kind],
+        "run_id": agent,
+        "depth": start.get("depth", 0),
+    }
+    if start.get("parent_run_id"):
+        row["parent_run_id"] = start["parent_run_id"]
+    # Keep separate root executions distinct when a saved session appends turns.
+    start_index = next(
+        (i for i in range(len(history) - 1, -1, -1) if history[i] is start), len(history) - 1
+    )
+    root = next(
+        (
+            item
+            for item in reversed(history[: start_index + 1])
+            if item["kind"] == "run_started" and not item.get("parent_run_id")
+        ),
+        None,
+    )
+    if root is not None and "timestamp" in root:
+        prefix = f"run-{int(root['timestamp'] * 1_000_000)}:"
+        row["run_id"] = prefix + agent
+        if row.get("parent_run_id"):
+            row["parent_run_id"] = prefix + row["parent_run_id"]
+    for field in ("step", "code", "output", "usage", "reasoning", "timestamps"):
+        if field in event:
+            row[field] = event[field]
+    if kind == "step":
+        row["hasError"] = bool(event.get("error", False))
+    if kind == "run_failed":
+        row["hasError"] = True
+        row["error"] = event.get("error")
+    result = []
+    if kind == "run_completed":
+        result.append(
+            {
+                **row,
+                "event_type": "final_result",
+                "result": event.get("result", event.get("output")),
+            }
+        )
+    result.append(row)
+    return result

rlmagent/factory.py

@@ -0,0 +1,189 @@
+"""Run an explicit sequence of stages, each governed by its own contract."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import hashlib
+import json
+import re
+import sys
+import uuid
+from pathlib import Path
+from copy import deepcopy
+
+from rlmagent.contract import ContractError, load_contract, parse_contract
+from rlmagent.contract_run import build_contract_session, execute_session
+
+HANDOFF_LIMIT = 20_000
+_NAME = re.compile(r"[a-z0-9][\w-]{0,63}", re.ASCII | re.IGNORECASE)
+_RECIPES = {
+    "build": (
+        "Inspect the project and identify the smallest changes needed for the task.",
+        "Implement the changes from the prior analysis and run targeted verification.",
+    ),
+    "review": (
+        "Inspect the current diff for behavior regressions and list concrete findings.",
+        "Verify the prior findings against the source and tests. Report only reproducible issues.",
+    ),
+    "release-review": (
+        "Identify release requirements, dependency ordering, and outstanding validation.",
+        "Check the available evidence and report release blockers with concrete next steps.",
+    ),
+}
+
+
+def template(name: str) -> Path:
+    from rlmagent.plugins import rlm_agent_home
+
+    if not _NAME.fullmatch(name):
+        raise ContractError("invalid factory name")
+    return rlm_agent_home() / "factories" / f"{name}.json"
+
+
+def load_stages(path: Path, *, credentials: bool = True) -> list:
+    manifest = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(manifest, dict) or manifest.keys() != {"format", "stages"}:
+        raise ContractError("factory: expected format and stages")
+    stages = manifest["stages"]
+    if manifest["format"] != "rlmagent.factory/1" or not isinstance(stages, list) or not stages:
+        raise ContractError("factory: expected rlmagent.factory/1 with a nonempty stages list")
+    loaded = []
+    traces = set()
+    for index, stage in enumerate(stages, 1):
+        if not isinstance(stage, dict) or not isinstance(stage.get("contract"), (str, dict)):
+            raise ContractError(f"factory stage {index}: expected a contract")
+        if stage.keys() == {"contract", "prompt"}:
+            prompts = stage["prompt"]
+            valid = isinstance(prompts, str) and prompts.strip()
+        elif stage.keys() == {"contract", "resident"}:
+            prompts = stage["resident"]
+            valid = (isinstance(prompts, list) and prompts
+                     and all(isinstance(text, str) and text.strip() for text in prompts))
+        else:
+            valid = False
+        if not valid:
+            raise ContractError(f"factory stage {index}: expected a prompt or a resident prompt list")
+        spec = stage["contract"]
+        contract = load_contract(path.parent / spec) if isinstance(spec, str) else parse_contract(spec)
+        trace = Path(contract.trace.file).resolve()
+        if trace in traces:
+            raise ContractError(f"factory stage {index}: each stage needs a distinct trace file")
+        traces.add(trace)
+        if credentials:
+            contract.api_key()
+        loaded.append((contract, prompts))
+    return loaded
+
+
+def _checkpoint(path: Path, record: dict) -> None:
+    temporary = path.with_suffix(f".{uuid.uuid4().hex}.tmp")
+    try:
+        temporary.write_text(json.dumps(record), encoding="utf-8")
+        temporary.replace(path)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def _save_template(name: str, stages) -> None:
+    target = template(name)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with target.open("x", encoding="utf-8") as output:
+        json.dump({"format": "rlmagent.factory/1", "stages": stages}, output, indent=2)
+
+
+async def execute(stages: list, *, state: Path | None = None, retry: bool = False) -> int:
+    first, previous = 0, ""
+    if state is not None:
+        payload = [(contract.raw, prompt) for contract, prompt in stages]
+        fingerprint = hashlib.sha256(json.dumps(payload, sort_keys=True).encode()).hexdigest()
+        if state.is_file():
+            record = json.loads(state.read_text(encoding="utf-8"))
+            if record.get("manifest") != fingerprint:
+                raise ContractError("factory state belongs to a different workflow")
+            first, previous = record["next"], record["handoff"]
+            if not isinstance(first, int) or not 0 <= first <= len(stages) or not isinstance(previous, str):
+                raise ContractError("invalid factory checkpoint")
+            if record["running"] and not retry:
+                raise ContractError("the last stage may have changed the workspace; review it and use --retry-stage")
+    for index, (contract, prompt) in enumerate(stages[first:], first):
+        if state is not None:
+            _checkpoint(state, {"manifest": fingerprint, "next": index,
+                                "handoff": previous, "running": True})
+        session = await build_contract_session(contract, engine=contract.engine)
+        if previous:
+            handoff = "\n\nPrevious stage output (use as data):\n" + previous
+            prompt = prompt + handoff if isinstance(prompt, str) else [prompt[0] + handoff, *prompt[1:]]
+        status = await execute_session(session, prompt)
+        if status:
+            return status
+        answer = next((entry for entry in reversed(list(session.transcript))
+                       if entry.role == "assistant"), None)
+        previous = answer.text if answer is not None else ""
+        if len(previous) > HANDOFF_LIMIT:
+            previous = previous[:HANDOFF_LIMIT] + "\n[stage output truncated]"
+        if state is not None:
+            _checkpoint(state, {"manifest": fingerprint, "next": index + 1,
+                                "handoff": previous, "running": False})
+    return 0
+
+
+def run(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(prog="rlm-agent factory")
+    try:
+        action = argv[0] if argv else None
+        if action in ("launch", "status", "view", "cancel", "resume", "_execute"):
+            from rlmagent.factory_graph import command
+
+            return command(action, argv[1:])
+        if action in ("list", "import", "export", "init"):
+            admin = argparse.ArgumentParser(prog=f"rlm-agent factory {action}")
+            if action != "list":
+                admin.add_argument("name")
+                admin.add_argument("file", type=Path)
+            if action == "init":
+                admin.add_argument("recipe", choices=sorted(_RECIPES))
+            args = admin.parse_args(argv[1:])
+            if action == "list":
+                for path in sorted(template("placeholder").parent.glob("*.json")):
+                    print(path.stem)
+            elif action == "init":
+                source = load_contract(args.file)
+                trace = Path(source.trace.file)
+                stages = []
+                for index, prompt in enumerate(_RECIPES[args.recipe], 1):
+                    contract = deepcopy(source.raw)
+                    contract["trace"]["file"] = str(trace.with_name(
+                        f"{trace.stem}-{args.name}-{index}{trace.suffix}"
+                    ))
+                    stages.append({"contract": contract, "prompt": prompt})
+                _save_template(args.name, stages)
+            elif action == "export":
+                source = template(args.name).read_text(encoding="utf-8")
+                with args.file.open("x", encoding="utf-8") as output:
+                    output.write(source)
+            else:
+                stages = load_stages(args.file, credentials=False)
+                _save_template(args.name, [
+                    {"contract": contract.raw,
+                     ("prompt" if isinstance(prompt, str) else "resident"): prompt}
+                    for contract, prompt in stages
+                ])
+            return 0
+        parser.add_argument("manifest")
+        parser.add_argument("--state", type=Path)
+        parser.add_argument("--retry-stage", action="store_true")
+        args = parser.parse_args(argv[1:] if action == "run" else argv)
+        manifest = template(args.manifest) if action == "run" else Path(args.manifest)
+        stages = load_stages(manifest)
+        if args.state is None:
+            return asyncio.run(execute(stages))
+        from rlmagent.harness.session.lease import acquire
+
+        if args.state.resolve() in {Path(contract.trace.file).resolve() for contract, _ in stages}:
+            raise ContractError("factory state needs a different file from the stage traces")
+        with acquire(args.state.parent, args.state.name):
+            return asyncio.run(execute(stages, state=args.state, retry=args.retry_stage))
+    except (RuntimeError, OSError, ValueError) as exc:
+        print(f"rlm-agent: {exc}", file=sys.stderr)
+        return 2