openrua 0.0.7__py3-none-any.whl

openrua/__init__.py

@@ -0,0 +1,31 @@
+"""OpenRUA: operating robots through their native command-line interface.
+
+Folders are units; top-level files compose or are shared (architecture
+contract in pyproject.toml, enforced by tests/test_layering.py):
+
+- ``robot``       the machine the agent operates, provided by a backend:
+                  sim/ (host side + bridge/, the simulated robot's own
+                  software, container) or real/ (a launch command and a
+                  handle that waits for the graph)
+- ``sandbox``     the agent's terminal: reachable machine + config ->
+                  live container (native CLI/rclpy inside)
+- ``proxy``       one shared whitelist proxy to the internet
+- ``agents``      the agent contract, the registry (manifests + hooks),
+                  the launcher, the prompts
+- ``runner``      running trials: bring-up, preflight (every promise the
+                  workspace docs make, verified before the agent starts;
+                  red = trial refused), the operator, the verdict, the
+                  record (sole runs/ writer), the lock
+- ``cli``, ``doctor``  the command line and the install check
+- ``config``, ``errors``, ``testing``  shared leaves
+
+openrua.robot.sim.bridge is container-side (rclpy); host code never
+imports it and reaches it only over DDS (the agent) or its stdio line
+(the runner).
+"""
+from importlib.metadata import PackageNotFoundError, version as _version
+
+try:
+    __version__ = _version("openrua")
+except PackageNotFoundError:  # a checkout that was never installed
+    __version__ = "0+unknown"

openrua/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m openrua`` is the same command line as ``openrua``."""
+
+import sys
+
+from openrua.cli import main
+
+sys.exit(main())

openrua/agents/__init__.py

@@ -0,0 +1,17 @@
+"""Agents: the contract, the registry, the launcher, the prompts.
+
+Every fact about a particular coding agent lives in its manifest
+(``configs/agents/<name>.yaml``) and its hooks module
+(``plugins/agents/<hooks>.py``); every consumer reaches an agent through
+``get(name)``. Configs carry ``agent.name`` (the package default is in
+``configs/config.yaml``), recorded per trial in ``operator_meta.agent``
+so post-hoc tools resolve the agent a trial actually ran.
+"""
+
+from openrua.agents.base import HOOK_NAMES, Agent, Credentials  # noqa: F401
+from openrua.agents.credentials import prepare_profile  # noqa: F401
+from openrua.agents.prompts import PROMPT, RESUME_PROMPT  # noqa: F401
+from openrua.agents.registry import (  # noqa: F401
+    Listed, Manifest, available, fact_sha256, get, manifest, manifests, preinstall,
+    split_pin, whitelist,
+)

openrua/agents/__main__.py

@@ -0,0 +1,28 @@
+"""``python -m openrua.agents launch ...``: run an agent headless in a live sandbox.
+
+The one verb this package exposes from the command line; image builds
+take their facts from the manifests through ``openrua build``.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from openrua.agents import launcher
+
+
+def main() -> int:
+    args = sys.argv[1:]
+    if not args or args[0] in ("-h", "--help"):
+        print("usage: python -m openrua.agents launch [options]\n"
+              "options: python -m openrua.agents launch --help")
+        return 0
+    if args[0] != "launch":
+        print(f"unknown verb {args[0]!r}; the only verb is launch", file=sys.stderr)
+        return 2
+    sys.argv = ["python -m openrua.agents launch", *args[1:]]
+    return launcher.main()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

openrua/agents/base.py

@@ -0,0 +1,231 @@
+"""The agent contract: what OpenRUA needs to know about one coding agent.
+
+An ``Agent`` is composed by the registry from two halves:
+
+- the manifest (``configs/agents/<name>.yaml``): the facts, set here as
+  plain attributes: name, default model, the shell that installs the
+  CLI into the sandbox image, the hosts it talks to, how it logs in;
+- the hooks module (``plugins/agents/<hooks>.py``, exposing ``HOOKS``,
+  a subclass of this class): the behaviour. One method is required,
+  ``launch_argv``, the docker-exec command that runs the agent headless
+  on a task. Every other hook has a documented default; a consumer that
+  finds the default does without (no interactive mode, no quota
+  bookkeeping, no replay). ``capabilities`` says which hooks a class
+  implements, so ``openrua agents`` and ``doctor`` can list them.
+
+Hooks take ``**_`` so the harness can pass new keyword arguments without
+breaking older hooks modules. ``openrua.testing.check_agent`` is the
+conformance test.
+
+Leaf module: imports nothing from openrua.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Credentials:
+    """How a CLI keeps its login, when it keeps one in a profile directory.
+
+    ``dirname``: the profile's directory name under ``~/.openrua/credentials/``.
+    ``filename``: the file inside it that holds the rotating secret. It is
+    bind-mounted as ONE shared file into every sandbox (OAuth refresh
+    tokens rotate; copies kill each other), the rest of the profile is a
+    fresh per-sandbox copy.
+    ``config_env``: the environment variable the CLI reads its profile
+    directory from.
+    ``mount_point``: where the profile lands inside the sandbox.
+    """
+    dirname: str
+    filename: str
+    config_env: str
+    mount_point: str
+
+
+# The optional hooks, in the order they are documented below. An agent
+# "has" a capability when its hooks class overrides the hook.
+HOOK_NAMES = (
+    "interactive_argv", "sandbox_cli_check", "login_hint", "token_hint",
+    "quota_probe_argv", "quota_window_open", "matches_quota_anomaly",
+    "read_rate_limits", "quota_since", "read_final", "scan_transcript",
+    "assistant_turns_before", "replay_ops", "collect",
+)
+
+
+class Agent:
+    """The contract. The manifest's fields arrive as keyword arguments;
+    a hooks module subclasses this and implements ``launch_argv``."""
+
+    # ---- required ---------------------------------------------------
+    name: str = ""                      # agent name (``agent.name`` in configs)
+    default_model: str = ""             # model when the config names none
+
+    # ---- manifest facts, all with defaults --------------------------
+    binary: str = ""                    # the CLI executable inside the sandbox
+    version: str | None = None          # the CLI version the install line pins
+    install: str = ""                   # one-line root shell chain that installs the
+                                        # CLI into the sandbox image ("" = nothing)
+    whitelist: tuple[str, ...] = ()     # hostname regexes the CLI must reach through
+                                        # the proxy (tinyproxy filter syntax)
+    credentials: Credentials | None = None   # profile-directory login, or None
+    token_env: str | None = None        # env var carrying a long-lived token, when
+                                        # the CLI accepts one (passed by file)
+    version_argv: tuple[str, ...] | None = None   # prints the CLI version (provenance)
+    instruction_file: str | None = None  # the instructions file this CLI reads on
+                                         # its own at start, if any; declared only,
+                                         # nothing is seeded from it yet
+    default_options: dict[str, Any] = {}  # knobs a config may override under
+                                          # ``agent.options``
+
+    def __init__(self, **fields: Any) -> None:
+        for k, v in fields.items():
+            if not hasattr(type(self), k):
+                raise TypeError(f"{type(self).__name__} has no attribute {k!r}")
+            setattr(self, k, v)
+        if not self.name or not self.default_model:
+            raise TypeError(f"{type(self).__name__}: name and default_model are required")
+
+    # ---- the one required method ------------------------------------
+    def launch_argv(self, sandbox: str, prompt: str, model: str, max_turns: int,
+                    proxy: str, options: dict[str, Any] | None = None,
+                    session_id: str | None = None, resume: bool = False,
+                    token_file: str | None = None, **_: Any) -> list[str]:
+        """The docker-exec command that runs the agent headless in
+        ``sandbox`` on ``prompt``, as the ``robot`` user in /workspace,
+        with ``proxy`` as its only route out, writing its transcript to
+        stdout. ``options`` are the merged adapter knobs. ``session_id``
+        names the session so ``resume=True`` can continue it later.
+        ``token_file`` is a host file holding ``<token_env>=<token>`` for
+        docker's ``--env-file``."""
+        raise NotImplementedError(f"{self.name}: launch_argv is required")
+
+    # ---- generic behaviour derived from the declarations ------------
+    @staticmethod
+    def exec_argv(sandbox: str, env: list[str] = (), token_file: str | None = None,
+                  interactive: bool = False) -> list[str]:
+        """The ``docker exec`` prefix every hook shares: the ``robot`` user
+        in /workspace, ``env`` as ``-e`` pairs already rendered, the
+        token file handed to the process by ``--env-file``, a terminal
+        when ``interactive``. Append the agent's own command."""
+        return [
+            "docker", "exec", *(["-it"] if interactive else []),
+            "-u", "robot", "-w", "/workspace",
+            *(["--env-file", token_file] if token_file else []),
+            *env,
+            sandbox,
+        ]
+
+    def sandbox_mounts(self, config_dir: Path,
+                       credentials_file: Path | None = None) -> tuple[str, ...]:
+        """SRC:DST mounts for the sandbox: the per-sandbox profile copy
+        at ``credentials.mount_point`` and, when one is given, the shared
+        credentials file inside it. Empty for an adapter without a
+        profile-directory login."""
+        if self.credentials is None:
+            return ()
+        c = self.credentials
+        mounts = (f"{config_dir}:{c.mount_point}",)
+        if credentials_file is None:
+            return mounts
+        return mounts + (f"{credentials_file}:{c.mount_point}/{c.filename}",)
+
+    def credentials_check(self) -> tuple[str, str] | None:
+        """(name, bash) preflight check that the mounted credentials file is
+        readable by the sandbox user. None without a profile login."""
+        if self.credentials is None:
+            return None
+        f = f"{self.credentials.mount_point}/{self.credentials.filename}"
+        return ("credentials_readable", f"bash -c '[ ! -e {f} ] || test -r {f}'")
+
+    @property
+    def capabilities(self) -> frozenset[str]:
+        """The hooks this agent's class implements (overrides)."""
+        return frozenset(h for h in HOOK_NAMES
+                         if getattr(type(self), h) is not getattr(Agent, h))
+
+    # ---- optional hooks; each docstring states the default ----------
+    def interactive_argv(self, sandbox: str, model: str, proxy: str,
+                         options: dict[str, Any] | None = None,
+                         prompt: str | None = None, **_: Any) -> list[str] | None:
+        """docker-exec command that opens the agent interactively in the
+        sandbox (a person at the keyboard). Default: None, meaning
+        ``openrua agent`` refuses with "no interactive mode"."""
+        return None
+
+    def sandbox_cli_check(self) -> tuple[str, str] | None:
+        """(name, bash) preflight check run inside the sandbox before the
+        agent starts (a version pin, say). Default: None, no check."""
+        return None
+
+    def login_hint(self, creds_home: Path) -> str:
+        """One line telling the operator how to log this CLI in with
+        ``creds_home`` as its profile directory. Default: a generic line."""
+        return (f"log the {self.name} CLI in with its profile directory "
+                f"set to {creds_home}")
+
+    def token_hint(self, token_file: Path | str) -> str | None:
+        """How to mint the token file ``launch_argv`` expects. Default:
+        None (this CLI takes no token file)."""
+        return None
+
+    def quota_probe_argv(self, model: str) -> list[str] | None:
+        """A minimal in-sandbox request whose outcome says whether the
+        account's quota window is open (see ``quota_window_open``).
+        Default: None, no probe; callers treat the window as open."""
+        return None
+
+    def quota_window_open(self, returncode: int, text: str) -> bool:
+        """Judge a probe's result. Default: True."""
+        return True
+
+    def matches_quota_anomaly(self, text: str) -> bool:
+        """Does a runner anomaly string look like a quota wall? Default: False."""
+        return False
+
+    def read_rate_limits(self, transcript: Path) -> list[dict]:
+        """Every quota reading the CLI wrote into a transcript, normalized
+        to ``{window, utilization, resets_at, status, at}``. Default: []."""
+        return []
+
+    def quota_since(self, transcript: Path, line: int = 0) -> dict | None:
+        """Quota-wall evidence written after ``line`` (``{evidence,
+        resets_at, ...}``), or None. Default: None, never a wall; the
+        runner then never suspends a trial."""
+        return None
+
+    def read_final(self, transcript: Path) -> dict:
+        """The trial's totals from the transcript: ``{num_turns,
+        hit_max_turns, usage, cost_usd, duration_ms, segments}``. Default:
+        {}, nothing known; the runner then counts turns as unknown."""
+        return {}
+
+    def scan_transcript(self, transcript: Path) -> dict | None:
+        """Classification evidence (``quota``, ``has_final_result``,
+        ``final_is_error``, ``api_transport_error``, ...). Default: None."""
+        return None
+
+    def assistant_turns_before(self, transcript: Path, wall_unix: float) -> int | None:
+        """Agent turns completed at or before an instant (post-hoc turn
+        budgets). Default: None, unknown."""
+        return None
+
+    def replay_ops(self, transcript: Path) -> list[dict]:
+        """The agent's world-facing operations in order, each one of
+        ``{kind: "shell", command}``, ``{kind: "write", path, content}`` or
+        ``{kind: "edit", path, old, new, replace_all}``, plus ``output``,
+        ``duration_s`` and the wall times ``t0``/``t1`` (unix seconds,
+        None when the transcript has none). Default: [] (no replay)."""
+        return []
+
+    def collect(self, profile_dir: Path, trial_dir: Path) -> list[Path]:
+        """After the run, before the sandbox's profile directory is
+        discarded: keep what this agent wants from it in the trial
+        directory (a CLI that writes its own session log there, say).
+        Returns the files written; they get the same secret scrub as the
+        transcript. The file names are this agent's alone: its reading
+        hooks find them beside the transcript. Default: nothing kept."""
+        return []

openrua/agents/credentials.py

@@ -0,0 +1,45 @@
+"""Staging an agent's login for one sandbox.
+
+The profile directory (settings and other non-rotating state) is always
+a fresh per-sandbox copy. The credentials file is never copied: OAuth
+refresh tokens rotate, and two copies of the file invalidate each other,
+so the one file is bind-mounted into every sandbox that needs it. A
+sandbox that authenticates with a token of its own needs no credentials
+file at all.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from openrua.agents.base import Agent
+
+
+def prepare_profile(creds_home: Path, agent: Agent, require_credentials: bool = True
+                    ) -> tuple[Path, Path | None]:
+    """Returns (profile_copy_dir, shared_credentials_file_or_None); the
+    caller owns deleting the copy dir.
+
+    With ``require_credentials`` the credentials file must exist and is
+    returned as a path for bind-mounting. Without it (a token
+    authenticates the sandbox) the second element is None. An agent
+    without a profile-directory login gets an empty copy dir and None.
+    """
+    cfg_dir = Path(tempfile.mkdtemp(prefix="openrua-agentcfg-"))
+    creds = agent.credentials
+    if creds is None:
+        return cfg_dir, None
+    creds_file: Path | None = creds_home / creds.filename
+    if not require_credentials:
+        creds_file = None
+    elif not creds_file.exists():
+        raise RuntimeError(f"credentials missing: {agent.login_hint(creds_home)}")
+    for pattern in ("*.json", ".*.json"):
+        for f in creds_home.glob(pattern):
+            if f.name != creds.filename:
+                shutil.copy2(f, cfg_dir / f.name)
+    subprocess.run(["chmod", "-R", "777", str(cfg_dir)])
+    return cfg_dir, creds_file

openrua/agents/launcher.py

@@ -0,0 +1,113 @@
+"""Headless agent launcher: run an agent in a live sandbox.
+
+The agent lives inside the sandbox: this module docker-execs the agent
+CLI in the sandbox container as the ``robot`` user in /workspace; all
+native tools operate in-sandbox and containment is the container
+itself. Invoked by the runner as a subprocess (never imported).
+Everything agent-specific (binary, flags, auth env, transcript format)
+comes from the agent selected by ``--agent``.
+
+``python -m openrua.agents.launcher --sandbox <container> --task
+"<sentence>" --transcript <path> [--prompt-file <path>] [--agent <name>]
+[--model ...] [--option k=v ...] [--max-turns N] [--proxy http://host:port]
+[--session-id <uuid>] [--resume] [--token-file <path>]``
+
+A trial suspended at a quota wall resumes by re-running this launcher with
+``--resume`` and the same ``--session-id``: the agent is shown the
+content-free resume prompt instead of the task (the session already holds
+it), and the new segment is APPENDED to the same transcript so one file
+still holds the whole trial.
+
+Network: the sandbox's only way out is the model-API proxy; the agent's
+hooks disable any server-side search the CLI offers (it cannot be
+proxied), verifiable in the transcript.
+
+The launcher is pure process construction: no prompt tricks, no aids.
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+from openrua import agents
+
+# Hand-run convenience only: the evaluator always passes the real URL it
+# got from proxy ensure. Must stay consistent with the proxy package's
+# defaults (leaves cannot import each other; tests/test_agents.py guards
+# the pair against drift).
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--sandbox", required=True)
+    ap.add_argument("--task", required=True)
+    ap.add_argument("--prompt-file", default=None,
+                    help="override prompt template with a {task} "
+                    "placeholder (default: agents.PROMPT)")
+    ap.add_argument("--transcript", required=True)
+    ap.add_argument("--agent", default=None,
+                    help="agent adapter name (default: openrua.agents default)")
+    ap.add_argument("--model", default=None,
+                    help="model id (default: the adapter's default_model)")
+    ap.add_argument("--option", action="append", default=[], metavar="KEY=VALUE",
+                    help="adapter knob (repeatable; the adapter's "
+                    "default_options apply underneath)")
+    ap.add_argument("--home", default=None,
+                    help="user directory holding agents/ (default: ~/.openrua)")
+    ap.add_argument("--max-turns", type=int, default=100)
+    ap.add_argument("--proxy", required=True, help="the proxy URL the sandbox reaches its model API through")
+    ap.add_argument("--session-id", default=None,
+                    help="name the session up front so it can be resumed")
+    ap.add_argument("--token-file", default=None,
+                    help="file holding the sandbox CLI's auth token as "
+                    "KEY=value; docker hands it to the CLI process only")
+    ap.add_argument("--resume", action="store_true",
+                    help="continue --session-id instead of starting it; the "
+                    "agent is shown agents.RESUME_PROMPT, not the task, and "
+                    "the transcript is appended to")
+    args = ap.parse_args()
+
+    if args.resume and not args.session_id:
+        ap.error("--resume needs the --session-id of the session to continue")
+
+    agent = agents.get(args.agent, args.home)
+    options = {}
+    for item in args.option:
+        if "=" not in item:
+            ap.error(f"--option expects KEY=VALUE, got {item!r}")
+        k, v = item.split("=", 1)
+        options[k] = v
+    if args.resume:
+        prompt = agents.RESUME_PROMPT
+    else:
+        template = Path(args.prompt_file).read_text() if args.prompt_file \
+            else agents.PROMPT
+        prompt = template.format(task=args.task)
+    cmd = agent.launch_argv(
+        sandbox=args.sandbox,
+        prompt=prompt,
+        model=args.model or agent.default_model,
+        max_turns=args.max_turns,
+        proxy=args.proxy,
+        options=options,
+        session_id=args.session_id,
+        resume=args.resume,
+        token_file=args.token_file,
+    )
+    # stderr goes to a sidecar, not DEVNULL: a launch-dead CLI (docker
+    # exec miss, bad flag) exits loud but used to leave zero evidence.
+    # Append on resume so the segments of one trial stay in one transcript;
+    # truncate otherwise, so a retried attempt never inherits a dead one's
+    # records.
+    mode = "a" if args.resume else "w"
+    with open(args.transcript, mode) as out, \
+            open(f"{args.transcript}.stderr", mode) as err:
+        proc = subprocess.run(cmd, stdout=out, stderr=err)
+    return proc.returncode
+
+
+if __name__ == "__main__":
+    sys.exit(main())

openrua/agents/prompts.py

@@ -0,0 +1,26 @@
+"""The two strings an agent is ever shown by the harness.
+
+``PROMPT`` opens a trial; ``{task}`` is its only placeholder. The
+launcher formats it and the trial record hashes the same string, so the
+hash pins the text the agent saw. ``RESUME_PROMPT`` is what a trial
+suspended at a quota wall receives when it continues: content-free on
+purpose, since the session already holds the task and the workspace,
+and restating either would hand a resumed trial context an
+uninterrupted one never had. A resumed trial still receives one more
+user turn than an uninterrupted one; that difference is recorded, not
+hidden.
+"""
+
+PROMPT = """\
+You are working on a robot's onboard computer.
+
+Your task: {task}
+
+Survey the machine yourself to find out what robot this is and what it
+can do; work until the task is physically done, verify it your own way,
+then finish.
+
+The workspace contains starter docs and tools you can use.
+"""
+
+RESUME_PROMPT = "Continue where you left off."