rlmness-cli 0.2.0__py3-none-any.whl

rlmagent/cli/main.py

@@ -0,0 +1,1194 @@
+"""CLI entry point for rlm-agent: argument parsing, mode dispatch, and lifecycle management."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import importlib.metadata
+import importlib.util
+import os
+import signal
+import sys
+from collections.abc import AsyncIterator, Sequence
+from pathlib import Path
+from typing import TYPE_CHECKING, NoReturn, TextIO
+
+if TYPE_CHECKING:
+    from rlmagent.conversation import CodingSession
+
+from rlmagent.safety import (
+    ApprovalContext,
+    ApprovalDecision,
+    ApprovalManager,
+    ApprovalPolicy,
+    clean_tool_result,
+    mark_untrusted,
+)
+from rlmagent.ui.render import OutputMode, make_renderer
+from rlmagent.harness.contracts.stream import AgentEvent
+from rlmagent.harness.contracts.tooling import ToolOutcome, ToolSpec
+from rlmagent.harness.contracts.transcript import CallBlock, surface_text
+from rlmagent.harness.driver import RuntimeHarness
+from rlmagent.harness.provider.base import ModelProvider
+from rlmagent.harness.session.index import SessionCatalog
+from rlmagent.harness.session.records import (
+    SessionMetaRecord,
+    TagRecord,
+    TranscriptRecord,
+)
+from rlmagent.harness.session.store import JsonlVault
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_PACKAGE = "rlmness-cli"
+_DEFAULT_ANTHROPIC_MODEL = "claude-opus-5"
+_DEFAULT_OPENAI_MODEL = "gpt-5"
+_DEFAULT_SYSTEM = "You are a helpful coding assistant."
+_SUBCOMMANDS = frozenset({"acp", "config", "doctor", "factory", "package", "provider", "session", "status", "tui",
+                          "update", "worker"})
+
+
+# ---------------------------------------------------------------------------
+# Version
+# ---------------------------------------------------------------------------
+
+
+def get_version() -> str:
+    """Resolve the installed package version, falling back to ``dev``."""
+    try:
+        return importlib.metadata.version(_PACKAGE)
+    except importlib.metadata.PackageNotFoundError:
+        return "dev"
+
+
+# ---------------------------------------------------------------------------
+# I/O helpers
+# ---------------------------------------------------------------------------
+
+
+def _info(msg: str) -> None:
+    sys.stderr.write(msg + "\n")
+    sys.stderr.flush()
+
+
+def _warn(msg: str) -> None:
+    sys.stderr.write(f"warning: {msg}\n")
+    sys.stderr.flush()
+
+
+def _die(msg: str) -> NoReturn:
+    sys.stderr.write(f"error: {msg}\n")
+    sys.stderr.flush()
+    sys.exit(1)
+
+
+# ---------------------------------------------------------------------------
+# Paths
+# ---------------------------------------------------------------------------
+
+
+def _sessions_dir(override: str | None = None) -> Path:
+    """Resolve the session directory from flag, env, or default."""
+    if override:
+        return Path(override)
+    from rlmagent.discovery import default_paths
+
+    return default_paths().sessions
+
+
+def _session_path(base: Path, session_id: str) -> Path:
+    return base / f"{session_id}.jsonl"
+
+
+# ---------------------------------------------------------------------------
+# Argument parsing
+# ---------------------------------------------------------------------------
+
+
+def _build_run_parser() -> argparse.ArgumentParser:
+    """Build the argument parser for the default run mode."""
+    p = argparse.ArgumentParser(
+        prog="rlm-agent",
+        description="rlm-agent - a coding agent with a persistent Python kernel and sub-agents.",
+    )
+    p.add_argument(
+        "--version", "-V", action="version", version=f"rlm-agent {get_version()}",
+    )
+    p.add_argument(
+        "prompt", nargs="?", default=None,
+        help="One-shot prompt (omit for interactive mode).",
+    )
+    p.add_argument(
+        "--print", "-p", dest="print_mode", action="store_true",
+        help="Non-interactive: stream final text only, then exit.",
+    )
+    p.add_argument("--model", "-m", default=None, help="Override model identifier.")
+    p.add_argument("--provider", default=None, help="Override provider backend.")
+    p.add_argument("--offline", action="store_true", help="Skip optional network discovery and update checks.")
+    p.add_argument(
+        "--resume", "-r", metavar="ID", default=None,
+        help="Resume a previous session by its ID.",
+    )
+    p.add_argument(
+        "--allow-private-fetch", action="store_true",
+        help="Let fetch_url reach local and private network addresses.",
+    )
+    p.add_argument(
+        "--resume-anywhere", action="store_true",
+        help="Allow --resume in a folder other than the one the session started in.",
+    )
+    p.add_argument("--session-dir", default=None, help="Session storage directory.")
+    p.add_argument("--system-prompt", default=None, help="Override system prompt.")
+    p.add_argument(
+        "--max-turns", type=int, default=None,
+        help="Limit agent turns per submission.",
+    )
+    p.add_argument("--verbose", "-v", action="store_true", help="Verbose diagnostics.")
+    p.add_argument("--no-auto-improve", dest="auto_improve", action="store_false",
+                   help="Do not update the playbook automatically.")
+    p.add_argument("--tools-at", default=None, metavar="SPEC",
+                   help="Run the workspace tools in a tool host instead of here: "
+                        "tcp://HOST:PORT (token in RLM_AGENT_TOOLS_TOKEN) or a command "
+                        "that serves over stdio, e.g. 'python -m rlmagent.toolhost --root /w'.")
+    p.add_argument("--deny-git", action="store_true",
+                   help="Refuse git commands that touch other branches, remotes or history "
+                        "(push, fetch, checkout, branch, tag, reset, ...).")
+    p.add_argument("--shell-access", choices=("workspace", "host"), default="workspace",
+                   help="Shell filesystem access: isolated workspace (default), or grant host access.")
+    p.add_argument("--shell-network", action="store_true",
+                   help="Allow network access from workspace-isolated shell commands.")
+    p.add_argument("--max-tool-output", type=int, default=None, metavar="BYTES",
+                   help="Most output one cell shows the model (default 20000; 0 disables this cap).")
+    p.add_argument("--max-compactions", type=int, default=None, metavar="N",
+                   help="Most context compactions in this session.")
+    p.add_argument("--agent-max-tokens", type=int, default=None, metavar="N",
+                   help="Most completion tokens any one agent may spend.")
+    p.add_argument("--search-block", action="append", default=None, metavar="DOMAIN",
+                   help="Drop web search results from this domain, *.domain or origin "
+                        "(repeatable).")
+    p.add_argument("--apply-auto-improve", dest="review_auto_improve", action="store_false",
+                   help="Save automatic playbook proposals at once instead of holding them "
+                        "for /improve accept.")
+    p.add_argument("--improve-every", type=int, default=5,
+                   help="Check whether to update the playbook every N finished tasks (default 5).")
+    p.add_argument("--improve-cooldown", type=float, default=900.0,
+                   help="Seconds between automatic playbook checks (default 900).")
+    p.add_argument("--kernel", choices=("wasm", "local"), default="wasm",
+                   help="Where the python tool runs: a WebAssembly sandbox (default) or a "
+                        "local IPython kernel.")
+    p.add_argument("--engine", choices=("session", "rlmness"), default="rlmness",
+                   help="Execution backend (default rlmness; session reads the previous engine).")
+    p.add_argument("--restore-kernel", action="store_true",
+                   help="Recover the last sandbox checkpoint after a restart (WASM only).")
+    p.add_argument("--no-network", dest="network", action="store_false",
+                   help="Keep the sandbox offline: no internet, no package installs.")
+    p.add_argument("--auto-approve", action="store_true",
+                   help="Let the sandbox write files and run commands without asking. "
+                        "Only for scratch folders.")
+    p.add_argument(
+        "--contract", metavar="FILE", default=None,
+        help="Run with exactly the settings in this run contract (JSON); needs -p.",
+    )
+    budget = p.add_argument_group("limits for the whole tree of agents")
+    budget.add_argument("--max-depth", type=int, default=2,
+                        help="How many levels of sub-agents may be started (default 2).")
+    budget.add_argument("--max-calls", type=int, default=None,
+                        help="Model calls allowed across all agents (default 200; 50 for acp: models).")
+    budget.add_argument("--max-cost", type=float, default=2.0,
+                        help="Spend allowed across all agents, in dollars (default 2.0).")
+    budget.add_argument("--max-agents", type=int, default=50,
+                        help="Sub-agents that may be started in one session (default 50).")
+    budget.add_argument("--max-live", type=int, default=8,
+                        help="Sub-agents running at the same time (default 8).")
+    budget.add_argument("--max-seconds", type=float, default=None,
+                        help="Wall-clock limit for the whole run (default none).")
+    budget.add_argument("--cell-timeout", type=float, default=300.0,
+                        help="Seconds one kernel cell may run before it is interrupted (default 300).")
+    budget.add_argument("--request-timeout", type=float, default=300.0,
+                        help="Deadline in seconds for each complete model response (default 300).")
+    p.add_argument(
+        "--no-session", action="store_true", help="Disable session persistence.",
+    )
+    p.add_argument("--idle-passivate", type=float, default=0, metavar="SECONDS",
+                   help="Let a saved worker exit after this much idle time (default disabled).")
+    p.add_argument(
+        "--repl", action="store_true",
+        help="Use the line-based REPL instead of the Textual UI.",
+    )
+    ownership = p.add_mutually_exclusive_group()
+    ownership.add_argument(
+        "--supervised", action="store_true",
+        help="Run the session in a background worker that keeps going when this window "
+             "closes, and attach to it.",
+    )
+    ownership.add_argument(
+        "--foreground", action="store_true",
+        help="Run the interactive session in this process (the default).",
+    )
+    trust = p.add_mutually_exclusive_group()
+    trust.add_argument(
+        "--approve", "-a", action="store_true",
+        help="Load this folder's project instructions, skills and plugins for this run.",
+    )
+    trust.add_argument(
+        "--no-approve", "-na", dest="no_approve", action="store_true",
+        help="Skip this folder's project inputs for this run.",
+    )
+    return p
+
+
+def _build_provider_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="rlm-agent provider")
+    sub = p.add_subparsers(dest="action", required=True)
+    sub.add_parser("list", help="List configured providers.")
+    sub.add_parser("setup", help="Interactive provider setup.")
+    for action in ("login", "logout"):
+        auth = sub.add_parser(action, help=f"{action.title()} a subscription account.")
+        auth.add_argument("name", choices=["codex", "copilot", "claude-subscription", "xai-subscription"])
+        if action == "login":
+            auth.add_argument("--new-account", action="store_true")
+            auth.add_argument("--client-registration", type=Path, default=None)
+    for action in ("models", "test"):
+        remote = sub.add_parser(action, help="Query the provider model endpoint.")
+        remote.add_argument("name")
+    sel = sub.add_parser("select", help="Set the active provider.")
+    sel.add_argument("name", help="Provider name to activate.")
+    return p
+
+
+def _build_session_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="rlm-agent session")
+    p.add_argument("--session-dir", default=None)
+    sub = p.add_subparsers(dest="action", required=True)
+    ls = sub.add_parser("list", help="List saved sessions.")
+    ls.add_argument("--session-dir", default=None, dest="sub_session_dir")
+    exp = sub.add_parser("export", help="Export a session to stdout.")
+    exp.add_argument("session_id", help="Session ID to export.")
+    exp.add_argument(
+        "--format", "-f", choices=["jsonl", "json", "text", "html"], default="jsonl",
+    )
+    exp.add_argument("--session-dir", default=None, dest="sub_session_dir")
+    share = sub.add_parser("share", help="Preview or explicitly publish an unlisted session gist.")
+    share.add_argument("session_id")
+    share.add_argument("--publish", action="store_true")
+    share.add_argument("--sha256", default=None, help="Digest of the exact previously reviewed payload")
+    share.add_argument("--session-dir", default=None, dest="sub_session_dir")
+    imp = sub.add_parser("import", help="Import a validated JSONL session under a new ID.")
+    imp.add_argument("file", type=Path)
+    imp.add_argument("--session-dir", default=None, dest="sub_session_dir")
+    st = sub.add_parser("stats", help="Print a session's token and cost totals as JSON.")
+    st.add_argument(
+        "session_id", nargs="?", default=None,
+        help="Session ID to summarize (default: the most recent session).",
+    )
+    st.add_argument("--session-dir", default=None, dest="sub_session_dir")
+    vw = sub.add_parser("view", help="Replay a session's agent steps as cards.")
+    vw.add_argument("session_id", nargs="?", default=None,
+                    help="Session ID (default: the most recent session).")
+    vw.add_argument("--session-dir", default=None, dest="sub_session_dir")
+    sp = sub.add_parser("steps", help="Per-agent steps, tokens, cost and time of a session.")
+    sp.add_argument("session_id", nargs="?", default=None,
+                    help="Session ID (default: the most recent session).")
+    sp.add_argument("--json", action="store_true", help="Print one JSON object per agent.")
+    sp.add_argument("--session-dir", default=None, dest="sub_session_dir")
+    pr = sub.add_parser("prune", help="List old sessions; remove them with --yes.")
+    pr.add_argument("--older-than", type=int, required=True, metavar="DAYS")
+    pr.add_argument("--yes", action="store_true", help="Actually remove them.")
+    pr.add_argument("--session-dir", default=None, dest="sub_session_dir")
+    return p
+
+
+# ---------------------------------------------------------------------------
+# Provider / model resolution
+# ---------------------------------------------------------------------------
+
+
+def _resolve_provider(name: str | None) -> ModelProvider:
+    """Build a ``ModelProvider`` from the given name, env, or config module."""
+    from rlmagent.config.config import resolve_provider
+    from rlmagent.model.settings import ConfigError
+
+    try:
+        return resolve_provider(name)
+    except ConfigError as exc:
+        _die(str(exc))
+
+
+def _resolve_provider_name(explicit: str | None) -> str:
+    """Provider name from the flag, then ``RLM_AGENT_PROVIDER``, then saved config."""
+    if explicit:
+        return explicit.strip().lower()
+    from rlmagent.config.loader import load_provider
+    return load_provider()
+
+
+def _resolve_model(override: str | None, provider_name: str = "anthropic") -> str:
+    """Model from the ``--model`` flag, ``RLM_AGENT_MODEL``, or the provider's default."""
+    explicit = override or os.environ.get("RLM_AGENT_MODEL")
+    if explicit:
+        return explicit
+    if provider_name == "openai":
+        return _DEFAULT_OPENAI_MODEL
+    if provider_name == "cli":
+        return "cli:claude-code"
+    if provider_name == "vertex":
+        return "google/gemini-3.5-flash"
+    if provider_name in ("google", "mistral", "azure", "codex", "copilot", "claude-subscription", "xai", "xai-subscription"):
+        from rlmagent.config.store import provider_info
+
+        return provider_info(provider_name).models[0]
+    return _DEFAULT_ANTHROPIC_MODEL
+
+
+def _resolve_system(
+    override: str | None,
+    *,
+    tools: Sequence[ToolSpec] = (),
+    skills: Sequence[object] = (),
+) -> str:
+    if override:
+        return override
+    try:
+        from rlmagent.instructions import system_prompt
+        return system_prompt(tools=tools, skills=skills)  # type: ignore[arg-type]
+    except (ImportError, AttributeError):
+        return _DEFAULT_SYSTEM
+
+
+# ---------------------------------------------------------------------------
+# Tool loading
+# ---------------------------------------------------------------------------
+
+
+def _load_tools(verbose: bool = False, kernel=None) -> list[ToolSpec]:
+    try:
+        from rlmagent.tools import build_tool_registry  # type: ignore[import-not-found]
+        tools: list[ToolSpec] = build_tool_registry(kernel)
+        if verbose:
+            _info(f"Loaded {len(tools)} tool(s).")
+        return tools
+    except (ImportError, AttributeError):
+        if verbose:
+            _info("Tool module not available; running without tools.")
+        return []
+
+
+# ---------------------------------------------------------------------------
+# Skill loading
+# ---------------------------------------------------------------------------
+
+
+def _load_skills(cwd: str, verbose: bool = False) -> list[object]:
+    """Load skills from all resource directories with full precedence."""
+    try:
+        from rlmagent.discovery import default_paths, skill_search_paths
+        from rlmagent.skillset import load_skills
+
+        paths = default_paths(project=Path(cwd))
+        dirs = skill_search_paths(paths)
+        skills = load_skills(dirs)
+        if verbose:
+            searched = ", ".join(str(d) for d in dirs)
+            _info(f"Loaded {len(skills)} skill(s) (searched: {searched}).")
+        return list(skills)
+    except (ImportError, AttributeError):
+        if verbose:
+            _info("Skill module not available; running without skills.")
+        return []
+
+
+def _load_prompt_templates(cwd: str, verbose: bool = False) -> list[object]:
+    """Load markdown prompt templates from all resource directories."""
+    try:
+        from rlmagent.discovery import default_paths, prompt_search_paths
+        from rlmagent.prompts import load_prompt_templates
+
+        paths = default_paths(project=Path(cwd))
+        dirs = prompt_search_paths(paths)
+        templates = load_prompt_templates(dirs)
+        if verbose:
+            searched = ", ".join(str(d) for d in dirs)
+            _info(f"Loaded {len(templates)} prompt template(s) (searched: {searched}).")
+        return list(templates)
+    except (ImportError, AttributeError):
+        if verbose:
+            _info("Prompt template module not available; running without templates.")
+        return []
+
+
+# ---------------------------------------------------------------------------
+# Hook wiring
+# ---------------------------------------------------------------------------
+
+
+def _install_hooks(harness: RuntimeHarness, verbose: bool = False) -> None:
+    try:
+        from rlmagent.hooks.hooks import install_hooks  # type: ignore[import-not-found]
+        install_hooks(harness)
+        if verbose:
+            _info("Hooks installed.")
+    except (ImportError, AttributeError):
+        pass
+
+
+_MUTATING_TOOLS = frozenset({"Write", "Edit", "python"})
+
+
+def _approval_context(call: CallBlock) -> ApprovalContext:
+    """Describe a pending tool call for the approval manager."""
+    args = call.arguments
+    command = args.get("command", args.get("code"))
+    path = args.get("file_path")
+    return ApprovalContext(
+        tool_name=call.name,
+        is_mutating=call.name in _MUTATING_TOOLS,
+        affected_paths=(str(path),) if isinstance(path, str) else (),
+        command=command if isinstance(command, str) else None,
+    )
+
+
+def _install_safety(harness: RuntimeHarness, policy: ApprovalPolicy) -> None:
+    """Gate tool calls through the approval manager and sanitize their results."""
+    manager = ApprovalManager(policy)
+
+    async def before_tool_call(call: CallBlock) -> tuple[bool, str | None]:
+        decision = await manager.check(_approval_context(call))
+        if decision is ApprovalDecision.APPROVED:
+            return False, None
+        return True, f"Blocked by safety policy ({decision.value}): {call.name}"
+
+    async def after_tool_call(
+        call: CallBlock, result: ToolOutcome, is_error: bool,
+    ) -> tuple[ToolOutcome, bool]:
+        return mark_untrusted(clean_tool_result(result)), is_error
+
+    harness.settings.before_tool_call = before_tool_call
+    harness.settings.after_tool_call = after_tool_call
+
+
+# ---------------------------------------------------------------------------
+# Extension loading
+# ---------------------------------------------------------------------------
+
+
+def _load_extensions(verbose: bool = False) -> list[object]:
+    """Discover and activate extensions from the extension directories."""
+    from rlmagent.plugins import load_extensions
+
+    result = load_extensions()
+
+    for failure in result.failures:
+        _warn(f"Extension {failure.name!r} failed: {failure.error}")
+
+    if verbose:
+        searched = ", ".join(str(path) for path in result.searched)
+        _info(f"Extensions: {result.count} loaded (searched: {searched})")
+        for extension in result.loaded:
+            _info(f"  {extension.name}  <- {extension.path}")
+
+    return [extension.value for extension in result.loaded]
+
+
+# ---------------------------------------------------------------------------
+# Session helpers
+# ---------------------------------------------------------------------------
+
+
+async def _list_sessions(base: Path, out: TextIO) -> None:
+    if not base.exists():
+        _info("No sessions found.")
+        return
+
+    # Prefer the catalog index when available
+    catalog = SessionCatalog(base)
+    entries = catalog.list_all()
+    if entries:
+        for meta in entries:
+            label = meta.title or meta.session_id
+            out.write(f"  {meta.session_id}  {label}  ({meta.provider}/{meta.model})\n")
+        return
+
+    # Fallback: scan vault files directly (pre-index sessions)
+    files = sorted(base.glob("*.jsonl"), key=lambda p: p.stat().st_mtime, reverse=True)
+    # Exclude the index file itself
+    files = [f for f in files if f.name != "index.jsonl"]
+    if not files:
+        _info("No sessions found.")
+        return
+    for path in files:
+        vault = JsonlVault(path)
+        try:
+            records = await vault.read_all()
+        except Exception:  # noqa: BLE001
+            out.write(f"  {path.stem}  (unreadable)\n")
+            continue
+        title = path.stem
+        n_messages = 0
+        for r in records:
+            if isinstance(r, TagRecord):
+                title = r.label
+            elif isinstance(r, SessionMetaRecord) and r.title:
+                title = r.title
+            elif isinstance(r, TranscriptRecord):
+                n_messages += 1
+        out.write(f"  {path.stem}  {title}  ({n_messages} messages)\n")
+
+
+async def _export_session(base: Path, sid: str, fmt: str, out: TextIO) -> None:
+    path = _session_path(base, sid)
+    if not path.exists():
+        _die(f"Session not found: {sid}")
+    records = await JsonlVault(path).read_all()
+    if fmt == "jsonl":
+        from rlmagent.harness.session.store import serialize_record
+        for r in records:
+            out.write(serialize_record(r))
+    elif fmt == "json":
+        from pydantic import TypeAdapter
+
+        from rlmagent.harness.session.records import SessionRecord
+        out.write(
+            TypeAdapter(list[SessionRecord]).dump_json(records, indent=2).decode() + "\n"
+        )
+    elif fmt == "html":
+        from rlmagent.session_html import render
+
+        out.write(render([], sid, records=records))
+    elif fmt == "text":
+        for r in records:
+            if isinstance(r, TranscriptRecord):
+                out.write(f"[{r.message.role}] {surface_text(r.message)}\n\n")
+
+
+def _latest_session_id(base: Path) -> str | None:
+    """Session id of the most recently modified vault file, if any."""
+    if not base.exists():
+        return None
+    # Run event logs sit beside the vaults as <id>.backend.events.jsonl; skip them.
+    files = [p for p in base.glob("*.jsonl") if p.name != "index.jsonl" and "." not in p.stem]
+    if not files:
+        return None
+    return max(files, key=lambda p: p.stat().st_mtime).stem
+
+
+async def _session_stats(base: Path, sid: str | None, out: TextIO) -> None:
+    """Write one JSON object of token and cost totals for a session."""
+    import json
+    from dataclasses import asdict
+
+    from rlmagent.harness.session.summary import summarize_records
+
+    resolved = sid or _latest_session_id(base)
+    if resolved is None:
+        _die("No sessions found.")
+    path = _session_path(base, resolved)
+    if not path.exists():
+        _die(f"Session not found: {resolved}")
+    records = await JsonlVault(path).read_all()
+    out.write(json.dumps(asdict(summarize_records(resolved, records))) + "\n")
+
+
+# ---------------------------------------------------------------------------
+# Provider subcommand
+# ---------------------------------------------------------------------------
+
+
+def _handle_provider(argv: list[str]) -> int:
+    ns = _build_provider_parser().parse_args(argv)
+
+    if ns.action in ("login", "logout"):
+        from rlmagent.model.settings import ConfigError
+        from rlmagent.model.subscription import login, logout
+
+        if ns.name == "xai-subscription":
+            from rlmagent.model import registered_oauth
+
+            try:
+                if ns.action == "login":
+                    asyncio.run(registered_oauth.login(ns.client_registration))
+                    _info("Registered OAuth token saved. Verify inference access separately.")
+                else:
+                    asyncio.run(registered_oauth.logout())
+                    _info("Local OAuth tokens cleared; provider-side revocation was not attempted.")
+                return 0
+            except (ConfigError, OSError, ValueError) as error:
+                _info(str(error))
+                return 1
+        if ns.name != "codex":
+            import shutil
+            import subprocess
+
+            executable = shutil.which("copilot" if ns.name == "copilot" else "claude")
+            if executable is None:
+                _info("Install the provider's official CLI to use its account sign-in.")
+                return 1
+            if ns.name == "copilot" and ns.action == "logout":
+                _info("Run /logout inside the official Copilot CLI to sign out.")
+                return 0
+            command = [executable, ns.action] if ns.name == "copilot" else [executable, "auth", ns.action]
+            return subprocess.run(command, check=False).returncode
+
+        try:
+            if ns.action == "login":
+                _info("Continue with ChatGPT in your browser. Waiting for consent...")
+                asyncio.run(login(new_account=ns.new_account))
+                _info("Subscription sign-in saved in the platform credential store. "
+                      "Use --provider codex to run an inference check.")
+            else:
+                confirmed = asyncio.run(logout())
+                _info("Signed out locally." + ("" if confirmed else
+                      " Remote revocation was not confirmed; disconnect in ChatGPT Settings."))
+            return 0
+        except ConfigError as exc:
+            _info(str(exc))
+            return 1
+
+    if ns.action in ("models", "test"):
+        from rlmagent.model.discovery import discover_models, check_provider
+        try:
+            if ns.action == "test":
+                _info(asyncio.run(check_provider(ns.name)))
+                return 0
+            models = asyncio.run(discover_models(ns.name))
+        except Exception as error:
+            # HTTP errors can contain endpoint details; never include authentication headers.
+            _info(f"Provider check failed: {type(error).__name__}")
+            return 1
+        if ns.action == "models":
+            for model in models:
+                print(model)
+        else:
+            _info(f"Provider model endpoint accepted credentials; {len(models)} models returned")
+        return 0
+    if ns.action == "list":
+        from rlmagent.config.config import list_providers
+        list_providers()
+        return 0
+
+    if ns.action == "setup":
+        from rlmagent.config.config import setup_provider
+        setup_provider()
+        return 0
+
+    if ns.action == "select":
+        from rlmagent.config.config import select_provider
+        from rlmagent.model.settings import ConfigError
+        try:
+            select_provider(ns.name)
+            _info(f"Active provider: {ns.name}")
+        except ConfigError as exc:
+            _die(str(exc))
+        return 0
+
+    return 1
+
+
+# ---------------------------------------------------------------------------
+# Session subcommand
+# ---------------------------------------------------------------------------
+
+
+def _textual_available() -> bool:
+    """Whether the optional ``textual`` extra is importable."""
+    return importlib.util.find_spec("textual") is not None
+
+
+def _handle_tui(ns: argparse.Namespace | None = None) -> int:
+    """Launch the Textual UI over the shared runtime session."""
+    if not _textual_available():
+        _die(
+            "The TUI requires the 'textual' extra.\n"
+            "  Install it with: pip install rlmness-cli[tui]"
+        )
+    from rlmagent.tui.app import run_tui
+    return run_tui(ns)
+
+
+def _should_launch_tui(ns: argparse.Namespace) -> bool:
+    """Whether a bare ``rlm-agent`` invocation should open the Textual UI."""
+    if ns.repl or ns.print_mode or ns.prompt is not None or ns.resume:
+        return False
+    if not (sys.stdin.isatty() and sys.stdout.isatty()):
+        return False
+    return _textual_available()
+
+
+def _handle_session(argv: list[str]) -> int:
+    if argv[:1] in (["detach"], ["attach"]):
+        from rlmagent.worker import handle_session
+
+        return handle_session(argv)
+    ns = _build_session_parser().parse_args(argv)
+    session_dir = ns.session_dir or getattr(ns, "sub_session_dir", None)
+    base = _sessions_dir(session_dir)
+
+    if ns.action == "list":
+        asyncio.run(_list_sessions(base, sys.stdout))
+        return 0
+
+    if ns.action == "export":
+        asyncio.run(_export_session(base, ns.session_id, ns.format, sys.stdout))
+        return 0
+    if ns.action == "share":
+        import json
+        import re
+
+        from rlmagent.harness.session.store import serialize_record
+        from rlmagent.session_html import render
+        from rlmagent.session_share import prepare, publish
+
+        if not re.fullmatch(r"[A-Za-z0-9_-]{1,128}", ns.session_id):
+            _die("Invalid session identifier")
+        async def share_session():
+            records = await JsonlVault(_session_path(base, ns.session_id)).read_all()
+            if not records:
+                raise ValueError("No session records found")
+            body, digest = prepare(ns.session_id, render(
+                [record.message for record in records if isinstance(record, TranscriptRecord)],
+                ns.session_id, records=records), "".join(serialize_record(record) for record in records))
+            if not ns.publish:
+                print(json.dumps(body, indent=2, ensure_ascii=False))
+                print(f"SHA-256: {digest}")
+                print("Unlisted gist: anyone with the link can read it. Nothing uploaded.")
+                return
+            print(await publish(body, expected_digest=ns.sha256,
+                                token=os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")))
+        try:
+            asyncio.run(share_session())
+        except (OSError, ValueError) as error:
+            _die(str(error))
+        return 0
+    if ns.action == "import":
+        from rlmagent.session_import import import_session
+
+        try:
+            print(import_session(ns.file, base))
+        except (OSError, ValueError) as exc:
+            _die(f"Cannot import session: {exc}")
+        return 0
+
+    if ns.action == "stats":
+        asyncio.run(_session_stats(base, ns.session_id, sys.stdout))
+        return 0
+
+    if ns.action in ("view", "steps"):
+        from rlmagent.tui.replay import (
+            ReplayApp, agent_rows, events_path, format_rows, load_events, runs_of,
+        )
+
+        resolved = ns.session_id or _latest_session_id(base)
+        if resolved is None:
+            _die("No sessions found.")
+        path = events_path(base, resolved)
+        if not path.exists():
+            _die(f"No agent steps saved for {resolved}; steps are kept for --engine rlmness.")
+        books = runs_of(load_events(path))
+        if ns.action == "view":
+            ReplayApp(resolved, books).run()
+            return 0
+        rows = agent_rows(books)
+        if ns.json:
+            import json
+            for row in rows:
+                print(json.dumps(row))
+        else:
+            print(format_rows(rows))
+        return 0
+
+    if ns.action == "prune":
+        from rlmagent.plugins import rlm_agent_home
+        from rlmagent.prune import prune
+
+        if ns.older_than < 1:
+            _die("--older-than must be at least 1 day.")
+        return prune(base, rlm_agent_home(), ns.older_than, apply=ns.yes)
+
+    return 1
+
+
+# ---------------------------------------------------------------------------
+# Event rendering
+# ---------------------------------------------------------------------------
+
+
+async def _consume_events(
+    events: AsyncIterator[AgentEvent],
+    *,
+    print_mode: bool,
+) -> bool:
+    """Consume the event stream and render output, returning overall success."""
+    mode = OutputMode.TEXT if print_mode else OutputMode.TRANSCRIPT
+    renderer = make_renderer(mode)
+    async for event in events:
+        renderer.render(event)
+    return renderer.finish()
+
+
+# ---------------------------------------------------------------------------
+# Run modes
+# ---------------------------------------------------------------------------
+
+
+#: ``/help`` is rendered from the shared command registry by the session, so
+#: this file keeps no command list of its own to drift out of date. Only the
+#: skill-invocation form, which is not a registered command, is appended.
+_HELP_SUFFIX = "  /skill:<name> [args]      Invoke a skill"
+
+
+async def _run_one_shot(
+    session: CodingSession,
+    prompt: str,
+    *,
+    print_mode: bool,
+) -> int:
+    """Submit a single prompt and exit."""
+    events = session.submit(prompt)
+    ok = await _consume_events(events, print_mode=print_mode)
+    ok = await _keep_going(session, ok, print_mode=print_mode)
+    sys.stdout.flush()
+    return 0 if ok else 1
+
+
+async def _keep_going(session: CodingSession, ok: bool, *, print_mode: bool) -> bool:
+    """Run the turns autonomous mode starts on its own, until it stops."""
+    pilot = getattr(session, "autopilot", None)
+    while ok and pilot is not None and (following := pilot.next_prompt()):
+        _info(f"[autonomous turn {pilot.turns}]")
+        ok = await _consume_events(session.submit(following), print_mode=print_mode)
+    if pilot is not None and pilot.stopped_because:
+        _info(f"[autonomous mode stopped: {pilot.stopped_because}]")
+        pilot.stopped_because = ""
+    return ok
+
+
+async def _run_interactive(session: CodingSession) -> int:
+    """Run the interactive prompt loop until the user exits."""
+    loop = asyncio.get_running_loop()
+    _info("Type /help for commands, /auto to toggle auto-accept, /quit to exit.\n")
+    tree = getattr(session, "agent_tree", None)
+    if tree is not None and tree.approver.policy in ("ask", "auto"):
+        tree.approver.ask = _ask_on_console
+    if tree is not None:
+        tree.approver.question = _question_on_console
+
+    while True:
+        try:
+            line = await loop.run_in_executor(None, _prompt_user)
+        except (EOFError, KeyboardInterrupt):
+            break
+
+        if line is None:
+            break
+        text = line.strip()
+        if not text:
+            continue
+
+        # CLI-level built-ins
+        if text in {"/quit", "/exit", "/q"}:
+            break
+        if text == "/version":
+            _info(f"rlm-agent v{get_version()}")
+            continue
+        if text == "/auto" and tree is not None:
+            on = tree.approver.toggle_auto()
+            _info("auto-accept on: file changes and commands go ahead unasked" if on
+                  else "auto-accept off: writes and commands ask first")
+            continue
+
+        # Resuming yields an event stream rather than a string, so it cannot go
+        # through handle_command like the other session commands.
+        if text in {"/continue", "/resume"}:
+            if session.active:
+                _warn("Agent is already running.")
+                continue
+            try:
+                events = session.resume_run()
+            except RuntimeError as exc:
+                _warn(str(exc))
+                continue
+            await _consume_events(events, print_mode=False)
+            continue
+
+        # Session-level slash commands (/model, /compact, /stats, /export, ...)
+        try:
+            response = await session.handle_command(text)
+        except Exception as exc:  # noqa: BLE001 - a bad command must not kill the REPL
+            _warn(f"Command failed: {exc}")
+            continue
+        if response is not None:
+            if text == "/help":
+                response = f"{response}\n{_HELP_SUFFIX}"
+            _info(response)
+            if text.split() in (["/autonomous"], ["/autonomous", "on"]):
+                await _keep_going(session, True, print_mode=False)
+            continue
+
+        # A registered command the session does not run (terminal-UI pickers and
+        # the like) must not reach the model as a prompt.
+        from rlmagent.conversation import COMMAND_REGISTRY
+        from rlmagent.directives import parse_command
+
+        parsed = parse_command(text)
+        command = COMMAND_REGISTRY.get(parsed[0]) if parsed is not None else None
+        if command is not None:
+            _warn(f"/{command.name.lstrip('/')} is not available in the line REPL.")
+            continue
+
+        # Ordinary prompt
+        try:
+            events = session.submit(text)
+        except RuntimeError as exc:
+            _warn(str(exc))
+            continue
+        ok = await _consume_events(events, print_mode=False)
+        await _keep_going(session, ok, print_mode=False)
+
+    return 0
+
+
+APPROVAL_KEYS = {"y": "once", "a": "always", "t": "auto", "n": "deny"}
+
+
+async def _ask_on_console(request) -> str:
+    """Line-mode approval: show what would change and read one key."""
+    from rlmagent.agents.approval import DENY
+
+    always = "this command" if request.kind == "run" else "this file"
+    _info(f"\nThe agent wants to:\n{request.describe()}")
+    question = f"Allow? [y] once  [a] always {always}  [t] and auto-accept the rest  [n] deny: "
+    loop = asyncio.get_running_loop()
+    while True:
+        try:
+            answer = await loop.run_in_executor(None, input, question)
+        except (EOFError, KeyboardInterrupt):
+            return DENY
+        choice = APPROVAL_KEYS.get(answer.strip().lower()[:1])
+        if choice is not None:
+            return choice
+
+
+async def _question_on_console(question: str, choices: list[str] | None, multiple: bool = False):
+    """Line-mode question: numbers pick choices (commas for several); anything else is the answer."""
+    _info(f"\nThe agent asks:\n{question}")
+    for number, choice in enumerate(choices or [], start=1):
+        _info(f"  {number}. {choice}")
+    try:
+        answer = await asyncio.get_running_loop().run_in_executor(None, input, "Answer: ")
+    except (EOFError, KeyboardInterrupt):
+        return None
+    answer = answer.strip()
+    picks = [p.strip() for p in answer.split(",")]
+    if multiple and choices and all(p.isdigit() and 1 <= int(p) <= len(choices) for p in picks):
+        return [choices[int(p) - 1] for p in picks]
+    if choices and answer.isdigit() and 1 <= int(answer) <= len(choices):
+        return choices[int(answer) - 1]
+    return answer or None
+
+
+def _prompt_user() -> str | None:
+    """Read a line of input from the user, returning ``None`` on EOF."""
+    try:
+        return input("\nrlm-agent> ")
+    except EOFError:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Signal handling
+# ---------------------------------------------------------------------------
+
+
+def _wire_signals(session: CodingSession) -> None:
+    """Install a SIGINT handler: first press aborts the active run, idle press"""
+
+    def _handler(_signum: int, _frame: object) -> None:
+        if session.active:
+            session.abort()
+            return
+        raise KeyboardInterrupt
+
+    signal.signal(signal.SIGINT, _handler)
+
+
+# ---------------------------------------------------------------------------
+# Startup banner
+# ---------------------------------------------------------------------------
+
+
+def _banner(provider: str, model: str, session_id: str | None, verbose: bool) -> None:
+    from rlmagent.config.store import PROVIDERS
+
+    label = next((p.label for p in PROVIDERS if p.key == provider), provider)
+    parts = [
+        f"rlm-agent v{get_version()}",
+        f"Provider: {label}",
+        f"Model: {model}",
+    ]
+    if session_id:
+        parts.append(f"Session: {session_id}")
+    if verbose:
+        parts.append(f"Python: {sys.version.split()[0]}")
+        parts.append(f"Cwd: {os.getcwd()}")
+    _info("\n".join(parts))
+
+
+# ---------------------------------------------------------------------------
+# Async orchestrator
+# ---------------------------------------------------------------------------
+
+
+async def _async_main(ns: argparse.Namespace) -> int:
+    """Wire everything together and dispatch to the chosen run mode."""
+    from rlmagent.runtime import build_session
+
+    if ns.contract:
+        from rlmagent.contract_run import run_contract
+
+        return await run_contract(ns)
+
+    # Piped stdin -> one-shot print mode
+    if ns.prompt is None and not sys.stdin.isatty():
+        ns.prompt = sys.stdin.read().strip()
+        if not ns.prompt:
+            _die("Empty input from stdin.")
+        ns.print_mode = True
+
+    if ns.print_mode and ns.prompt is None:
+        _die("Print mode requires a prompt (positional argument or stdin).")
+
+    # Shared construction — identical to the path the TUI uses.
+    session = await build_session(ns)
+    _wire_signals(session)
+
+    if not ns.print_mode:
+        _banner(session.provider_name, session.model, session.session_id, ns.verbose)
+
+    # --- dispatch ------------------------------------------------------
+
+    try:
+        if ns.prompt:
+            return await _run_one_shot(session, ns.prompt, print_mode=ns.print_mode)
+        return await _run_interactive(session)
+    finally:
+        await session.shutdown()
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Top-level CLI entry point for rlm-agent."""
+    # Model output is Unicode; a redirected Windows stream defaults to a legacy codepage.
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8", errors="replace")
+    args = list(argv if argv is not None else sys.argv[1:])
+    if "--offline" in args:
+        os.environ["RLM_AGENT_OFFLINE"] = "1"
+        args.remove("--offline")
+    from rlmagent.packages import activate
+
+    activate()
+
+    if "--acp" in args:
+        from rlmagent.acp.server import run as serve_acp
+
+        args.remove("--acp")
+        return serve_acp(args)
+
+    # Subcommand dispatch (checked before argparse to avoid positional conflicts)
+    if args and args[0] in _SUBCOMMANDS:
+        cmd, rest = args[0], args[1:]
+        if cmd == "package":
+            from rlmagent.packages import run
+
+            return run(rest)
+        if cmd == "acp":
+            from rlmagent.model.external.acp_install import main as acp_main
+            return acp_main(rest)
+        if cmd == "config":
+            from rlmagent.cli.config_cmd import handle_config
+            return handle_config(rest)
+        if cmd == "factory":
+            from rlmagent.factory import run
+
+            return run(rest)
+        if cmd == "tui":
+            ns = _build_run_parser().parse_args(rest)
+            if ns.supervised or _saved_interactive(ns):
+                return _handle_supervised(ns, rest, tui=True)
+            return _handle_tui(ns)
+        if cmd == "provider":
+            return _handle_provider(rest)
+        if cmd == "session":
+            return _handle_session(rest)
+        if cmd == "worker":
+            from rlmagent.worker import handle
+
+            return handle(rest)
+        if cmd == "update":
+            from rlmagent.cli.update import run
+
+            return run(rest)
+        if cmd in ("status", "doctor"):
+            from rlmagent.cli.health import run
+
+            return run(rest, doctor=cmd == "doctor")
+
+    # Default: run mode
+    ns = _build_run_parser().parse_args(args)
+
+    # A background worker owns the session only when asked for, or when the session
+    # being resumed already has one; otherwise the full UI runs in this process.
+    if ns.supervised or (_saved_interactive(ns) and sys.stdin.isatty()
+                         and _live_worker_owns(ns.resume)):
+        tui = not ns.repl and sys.stdin.isatty() and sys.stdout.isatty() and _textual_available()
+        return _handle_supervised(ns, args, tui=tui)
+
+    # Explicit foreground and no-session runs can still use the in-process TUI.
+    if not ns.contract and _should_launch_tui(ns):
+        return _handle_tui(ns)
+
+    try:
+        return asyncio.run(_async_main(ns))
+    except KeyboardInterrupt:
+        _info("\nInterrupted.")
+        return 130
+
+
+def _live_worker_owns(session_id: str | None) -> bool:
+    """Whether a running background worker holds this saved session."""
+    if not session_id:
+        return False
+    from rlmagent import worker
+
+    for name in worker._worker_names():
+        meta = worker.state_of(name)
+        if meta.get("session") == session_id and (meta["alive"] or worker._supervised(meta)):
+            return True
+    return False
+
+
+def _saved_interactive(ns: argparse.Namespace) -> bool:
+    return not (ns.foreground or ns.no_session or ns.contract or ns.print_mode or ns.prompt is not None)
+
+
+def _handle_supervised(ns: argparse.Namespace, args: list[str], *, tui: bool) -> int:
+    if ns.no_session or ns.contract or ns.print_mode or ns.prompt is not None:
+        _die("--supervised requires an interactive saved session")
+    from rlmagent.worker import start_interactive
+
+    if tui and not _textual_available():
+        _die("The TUI requires the 'textual' extra. Install it with: pip install rlmness-cli[tui]")
+    try:
+        return start_interactive(args, session_id=ns.resume, tui=tui)
+    except ValueError as error:
+        _die(str(error))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())