obey-cli 0.1.0__py3-none-any.whl

obey_cli/runner/sandbox.py

@@ -0,0 +1,341 @@
+"""Run one agent invocation in a Docker container with no direct route to the internet.
+
+Layout per batch: an internal Docker network, and a sidecar container on that network (alias `obey-gw`) that is
+also attached to the default bridge. The sidecar runs the model gateway (port 8787, holds the API key) and the
+allow-listing egress proxy (port 3128). Agent containers join only the internal network, so the proxy is their
+only way out and the gateway is their only model endpoint.
+
+Files move in and out with `docker cp` tar streams rather than bind mounts, so the sandbox works the same with
+Docker Desktop, colima or a remote daemon, and the agent never sees a host path.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import os
+import shutil
+import subprocess
+import tarfile
+import time
+import uuid
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+AGENT_UID = 1000
+AGENT_HOME = "/home/agent"
+WORK_ROOT = "/srv/obey"  # holds work/ (the repository copy) and .remote/ (a bare origin)
+GATEWAY_HOST = "obey-gw"
+GATEWAY_PORT = 8787
+PROXY_PORT = 3128
+SIDECAR_FILES = ("gateway.py", "egress_proxy.py", "sidecar.py")
+
+
+class SandboxError(RuntimeError):
+    pass
+
+
+@dataclass
+class Invocation:
+    """What an adapter asks the sandbox to run."""
+
+    argv: list[str]
+    env: dict[str, str] = field(default_factory=dict)
+    home_files: dict[str, str] = field(default_factory=dict)  # path relative to $HOME -> content
+    timeout_s: int = 600
+
+
+@dataclass
+class RawRun:
+    root: Path | None  # the copied-back WORK_ROOT (work/ and .remote/) when requested
+    out_dir: Path  # $HOME/.obey-out: stream.jsonl, stderr.log, exit_code, end-state.json, hook logs
+    exit_code: int | None
+    timed_out: bool
+    duration_s: float
+
+
+def docker_cmd() -> list[str]:
+    return os.environ.get("OBEY_DOCKER", "docker").split()
+
+
+def _docker(
+    *args: str,
+    input_bytes: bytes | None = None,
+    timeout: float = 120,
+    env: Mapping[str, str] | None = None,
+    check: bool = True,
+) -> subprocess.CompletedProcess[bytes]:
+    proc = subprocess.run(
+        [*docker_cmd(), *args],
+        input=input_bytes,
+        capture_output=True,
+        timeout=timeout,
+        env={**os.environ, **(env or {})},
+        check=False,
+    )
+    if check and proc.returncode != 0:
+        raise SandboxError(f"docker {args[0]} failed: {proc.stderr.decode('utf-8', 'replace')[:400]}")
+    return proc
+
+
+def docker_available() -> bool:
+    if shutil.which(docker_cmd()[0]) is None:
+        return False
+    try:
+        return _docker("info", "--format", "{{.ServerVersion}}", timeout=20, check=False).returncode == 0
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+
+
+def tar_tree(entries: Mapping[str, Path | str | bytes], mode_exec: Sequence[str] = ()) -> bytes:
+    """A tar archive owned by the sandbox user. Values are directories/files on disk or literal contents."""
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w") as tar:
+
+        def own(info: tarfile.TarInfo) -> tarfile.TarInfo:
+            info.uid = info.gid = AGENT_UID
+            info.uname = info.gname = "agent"
+            return info
+
+        for name, value in entries.items():
+            if isinstance(value, Path):
+                tar.add(value, arcname=name, filter=own)
+                continue
+            data = value.encode() if isinstance(value, str) else value
+            info = own(tarfile.TarInfo(name))
+            info.size = len(data)
+            info.mode = 0o755 if name in mode_exec else 0o644
+            info.mtime = int(time.time())
+            # Parent directories are created by docker cp with root ownership unless listed; add them.
+            parts = name.split("/")[:-1]
+            for i in range(1, len(parts) + 1):
+                d = own(tarfile.TarInfo("/".join(parts[:i])))
+                d.type = tarfile.DIRTYPE
+                d.mode = 0o755
+                if d.name not in tar.getnames():
+                    tar.addfile(d)
+            tar.addfile(info, io.BytesIO(data))
+    return buf.getvalue()
+
+
+@dataclass
+class Batch:
+    network: str
+    sidecar: str
+    image: str
+    allow_hosts: list[str]
+    started: bool = False
+
+    @property
+    def gateway_url(self) -> str:
+        return f"http://{GATEWAY_HOST}:{GATEWAY_PORT}"
+
+
+class DockerSandbox:
+    def __init__(self, image: str, *, cpus: str = "2", memory: str = "4g", pids: int = 1024):
+        self.image = image
+        self.cpus = cpus
+        self.memory = memory
+        self.pids = pids
+
+    def start_batch(
+        self,
+        *,
+        key: str,
+        model: str | None,
+        price: Mapping[str, float],
+        allow_hosts: Sequence[str],
+        run_cap: float | None,
+        budget: float | None,
+        upstreams: Mapping[str, str] | None = None,
+        run_ids: Sequence[str] | None = None,
+    ) -> Batch:
+        tag = uuid.uuid4().hex[:10]
+        batch = Batch(
+            network=f"obey-net-{tag}", sidecar=f"obey-gw-{tag}", image=self.image, allow_hosts=list(allow_hosts)
+        )
+        _docker("network", "create", "--internal", batch.network)
+        # The sidecar's configuration holds the key: never leave it behind when the batch fails to start.
+        try:
+            args = ["--model", model] if model else []
+            for name, value in price.items():
+                args += [f"--price-{name.replace('_', '-')}", str(value)]
+            if run_cap is not None:
+                args += ["--run-cap", str(run_cap)]
+            if budget is not None:
+                args += ["--budget", str(budget)]
+            for api, url in (upstreams or {}).items():
+                args += ["--upstream", f"{api}={url}"]
+            for host in allow_hosts:
+                args += ["--allow", host]
+            # Registered run ids: a run cannot reset its spend cap by calling the gateway under another id.
+            for run_id in run_ids or ():
+                args += ["--run-id", run_id]
+            _docker(
+                "create",
+                "--name",
+                batch.sidecar,
+                "--network",
+                "bridge",
+                "--entrypoint",
+                "python3",
+                "-e",
+                "OBEY_UPSTREAM_KEY",
+                "--cpus",
+                "1",
+                "--memory",
+                "512m",
+                "--pids-limit",
+                "256",
+                self.image,
+                f"{AGENT_HOME}/sidecar/sidecar.py",
+                *args,
+                env={"OBEY_UPSTREAM_KEY": key},
+            )
+            here = Path(__file__).parent
+            files = {f"sidecar/{name}": (here / name).read_bytes() for name in SIDECAR_FILES}
+            _docker("cp", "-a", "-", f"{batch.sidecar}:{AGENT_HOME}", input_bytes=tar_tree(files))
+            _docker("network", "connect", "--alias", GATEWAY_HOST, batch.network, batch.sidecar)
+            _docker("start", batch.sidecar)
+            batch.started = True
+            self._wait_ready(batch)
+        except BaseException:
+            self.stop_batch(batch)
+            raise
+        return batch
+
+    def _wait_ready(self, batch: Batch, timeout_s: float = 30) -> None:
+        probe = (
+            "import socket,sys\n"
+            f"for p in ({GATEWAY_PORT},{PROXY_PORT}):\n"
+            "    socket.create_connection(('127.0.0.1',p),timeout=1).close()\n"
+        )
+        deadline = time.monotonic() + timeout_s
+        while time.monotonic() < deadline:
+            if _docker("exec", batch.sidecar, "python3", "-c", probe, check=False).returncode == 0:
+                return
+            time.sleep(0.5)
+        logs = _docker("logs", batch.sidecar, check=False).stderr.decode("utf-8", "replace")[-800:]
+        raise SandboxError(f"sidecar did not become ready: {logs}")
+
+    def run(
+        self,
+        batch: Batch,
+        root: Path,
+        inv: Invocation,
+        out_dir: Path,
+        run_id: str,
+        *,
+        base_sha: str | None = None,
+        copy_back_work: bool = False,
+    ) -> RawRun:
+        """Copy `root` (work/ and .remote/) into the container, run the invocation, copy everything back."""
+        name = f"obey-run-{run_id[:40]}-{uuid.uuid4().hex[:6]}"
+        proxy = f"http://{GATEWAY_HOST}:{PROXY_PORT}"
+        env = {
+            "HOME": AGENT_HOME,
+            "HTTPS_PROXY": proxy,
+            "https_proxy": proxy,
+            "HTTP_PROXY": proxy,
+            "http_proxy": proxy,
+            "NO_PROXY": f"{GATEWAY_HOST},localhost,127.0.0.1",
+            "no_proxy": f"{GATEWAY_HOST},localhost,127.0.0.1",
+            **inv.env,
+        }
+        if base_sha:
+            env["OBEY_BASE_SHA"] = base_sha
+        env_args: list[str] = []
+        for k, v in env.items():
+            env_args += ["-e", f"{k}={v}"]
+        _docker(
+            "create",
+            "--name",
+            name,
+            "--network",
+            batch.network,
+            "--cpus",
+            self.cpus,
+            "--memory",
+            self.memory,
+            "--pids-limit",
+            str(self.pids),
+            "--security-opt",
+            "no-new-privileges",
+            "--cap-drop",
+            "ALL",
+            *env_args,
+            self.image,
+            str(inv.timeout_s),
+            *inv.argv,
+        )
+        try:
+            entries: dict[str, Path | str | bytes] = {"work": root / "work"}
+            if (root / ".remote").exists():
+                entries[".remote"] = root / ".remote"
+            _docker("cp", "-a", "-", f"{name}:{WORK_ROOT}", input_bytes=tar_tree(entries), timeout=300)
+            home: dict[str, Path | str | bytes] = {".obey-out/.keep": "", **inv.home_files}
+            if base_sha:
+                home[".obey-tools/workspace.py"] = (Path(__file__).parent / "workspace.py").read_bytes()
+            _docker("cp", "-a", "-", f"{name}:{AGENT_HOME}", input_bytes=tar_tree(home), timeout=60)
+            started = time.monotonic()
+            timed_out = False
+            try:
+                _docker("start", "-a", name, timeout=inv.timeout_s + 60, check=False)
+            except subprocess.TimeoutExpired:
+                timed_out = True
+                _docker("kill", name, check=False)
+            duration = time.monotonic() - started
+            out_dir.mkdir(parents=True, exist_ok=True)
+            if copy_back_work:
+                _extract(_docker("cp", f"{name}:{WORK_ROOT}", "-", timeout=300).stdout, out_dir)
+            _extract(_docker("cp", f"{name}:{AGENT_HOME}/.obey-out", "-", timeout=120).stdout, out_dir, files_only=True)
+            code_file = out_dir / ".obey-out" / "exit_code"
+            exit_code = int(code_file.read_text().strip()) if code_file.exists() else None
+            # GNU timeout exits 124, or 137 when the agent ignored TERM and was killed after the grace period.
+            if exit_code == 124 or (exit_code == 137 and duration >= inv.timeout_s):
+                timed_out = True
+            return RawRun(
+                root=out_dir / "obey" if copy_back_work else None,
+                out_dir=out_dir / ".obey-out",
+                exit_code=exit_code,
+                timed_out=timed_out,
+                duration_s=duration,
+            )
+        finally:
+            _docker("rm", "-f", name, check=False)
+
+    def ledger_lines(self, batch: Batch) -> list[dict[str, Any]]:
+        proc = _docker(
+            "exec", batch.sidecar, "sh", "-c", f"cat {AGENT_HOME}/ledger.jsonl 2>/dev/null || true", check=False
+        )
+        return [json.loads(line) for line in proc.stdout.decode().splitlines() if line.strip()]
+
+    def egress_log(self, batch: Batch) -> list[dict[str, Any]]:
+        proc = _docker(
+            "exec", batch.sidecar, "sh", "-c", f"cat {AGENT_HOME}/egress.jsonl 2>/dev/null || true", check=False
+        )
+        return [json.loads(line) for line in proc.stdout.decode().splitlines() if line.strip()]
+
+    def stop_batch(self, batch: Batch) -> None:
+        _docker("rm", "-f", batch.sidecar, check=False)
+        _docker("network", "rm", batch.network, check=False)
+
+
+def _safe_member(member: tarfile.TarInfo, dest: str) -> tarfile.TarInfo | None:
+    # Agents create virtualenvs and node_modules with absolute symlinks; skip anything the data filter rejects.
+    try:
+        return tarfile.data_filter(member, dest)
+    except tarfile.FilterError:
+        return None
+
+
+def _files_only(member: tarfile.TarInfo, dest: str) -> tarfile.TarInfo | None:
+    # The run's output directory holds only regular files: links and devices are dropped before the data filter.
+    return _safe_member(member, dest) if member.isfile() or member.isdir() else None
+
+
+def _extract(archive: bytes, dest: Path, *, files_only: bool = False) -> None:
+    with tarfile.open(fileobj=io.BytesIO(archive), mode="r") as tar:
+        tar.extractall(dest, filter=_files_only if files_only else _safe_member)  # noqa: S202 - filtered members

obey_cli/runner/sidecar.py

@@ -0,0 +1,38 @@
+"""Sidecar process for a sandbox batch: the model gateway and the egress proxy (standard library only).
+
+OBEY_UPSTREAM_KEY=... python3 sidecar.py [gateway options] --allow host [--allow host ...]
+"""
+
+import argparse
+import asyncio
+import os
+import sys
+import threading
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+import egress_proxy
+import gateway
+
+HOME = os.path.expanduser("~")
+# Host headers the gateway accepts: the network alias, and the in-container forwarder (sandbox/entrypoint.sh) that
+# Gemini CLI uses because it takes plain HTTP only on localhost.
+ALLOWED_HOSTS = ("obey-gw:8787", "127.0.0.1:8788")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--allow", action="append", default=[])
+    known, rest = parser.parse_known_args()
+    rest += ["--listen", "0.0.0.0:8787", "--ledger", os.path.join(HOME, "ledger.jsonl")]
+    for host in ALLOWED_HOSTS:
+        rest += ["--allowed-host", host]
+    gateway_thread = threading.Thread(target=gateway.main, args=(rest,), daemon=True)
+    gateway_thread.start()
+    proxy = egress_proxy.Proxy(known.allow, os.path.join(HOME, "egress.jsonl"))
+    asyncio.run(egress_proxy.serve("0.0.0.0:3128", proxy))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

obey_cli/runner/workspace.py

@@ -0,0 +1,187 @@
+"""Build the repository copy an agent works in, and read back what it did.
+
+Only tracked files enter a probe copy (`git ls-files` plus the probe's setup patch), so `.env` files, local
+secrets and ignored build output never reach the sandbox or the model provider. The copy gets a fresh git
+history with one neutral commit and, in container mode, a local bare `origin` so pushes can be detected.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+GIT_ENV = {
+    "GIT_AUTHOR_NAME": "Developer",
+    "GIT_AUTHOR_EMAIL": "dev@example.com",
+    "GIT_COMMITTER_NAME": "Developer",
+    "GIT_COMMITTER_EMAIL": "dev@example.com",
+    "GIT_AUTHOR_DATE": "2026-01-05T09:00:00+00:00",
+    "GIT_COMMITTER_DATE": "2026-01-05T09:00:00+00:00",
+    "GIT_CONFIG_NOSYSTEM": "1",
+    "GIT_TERMINAL_PROMPT": "0",
+}
+MAX_DIFF_BYTES = 2_000_000
+
+
+class WorkspaceError(RuntimeError):
+    pass
+
+
+def git(cwd: Path, *args: str, env: Mapping[str, str] | None = None, check: bool = True) -> str:
+    # HOME points at the copy so the user's global git configuration (signing, hooks, aliases) never applies.
+    full_env = {**os.environ, **GIT_ENV, "HOME": str(cwd), **(env or {})}
+    proc = subprocess.run(["git", *args], cwd=cwd, env=full_env, capture_output=True, check=False, timeout=120)
+    if check and proc.returncode != 0:
+        raise WorkspaceError(f"git {' '.join(args)} failed: {proc.stderr.decode('utf-8', 'replace')[:500]}")
+    return proc.stdout.decode("utf-8", "replace")
+
+
+def tracked_files(repo: Path) -> list[str]:
+    """Tracked paths relative to `repo` (which may be a subdirectory of a git repository)."""
+    if shutil.which("git") is None:
+        raise WorkspaceError("git is not installed")
+    probe = subprocess.run(["git", "-C", str(repo), "rev-parse", "--is-inside-work-tree"], capture_output=True)
+    if probe.returncode != 0:
+        raise WorkspaceError(f"{repo} is not inside a git repository; obey copies tracked files only")
+    out = subprocess.run(["git", "-C", str(repo), "ls-files", "-z", "--", "."], capture_output=True, check=True)
+    return sorted(p for p in out.stdout.decode("utf-8", "replace").split("\0") if p)
+
+
+@dataclass
+class ProbeCopy:
+    root: Path  # parent directory: work/ and .remote/ live inside
+    work: Path
+    base_sha: str
+    base_files: list[str]
+    remote: Path | None
+
+
+def build_probe_copy(
+    source: Path,
+    dest: Path,
+    *,
+    overrides: Mapping[str, str | None] | None = None,
+    extra_files: Mapping[str, str] | None = None,
+    setup_patch: str | None = None,
+    with_remote: bool = True,
+    files: Sequence[str] | None = None,
+    git_hooks: Mapping[str, str] | None = None,
+) -> ProbeCopy:
+    """Copy tracked files of `source` into `dest/work`, apply overrides and the setup patch, commit once.
+
+    `overrides` replaces (str) or removes (None) files by relative path, for example an instruction file with one
+    rule removed. `extra_files` adds files (generated enforcement) before the base commit.
+    """
+    work = dest / "work"
+    if work.exists():
+        shutil.rmtree(work)
+    work.mkdir(parents=True)
+    for rel in files if files is not None else tracked_files(source):
+        src = source / rel
+        if src.is_symlink() or not src.is_file():
+            continue
+        target = work / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(src, target)
+    for rel, content in {**(overrides or {}), **(extra_files or {})}.items():
+        target = work / rel
+        if content is None:
+            target.unlink(missing_ok=True)
+            continue
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8")
+    git(work, "init", "-q", "-b", "main")
+    if setup_patch:
+        patch = dest / "setup.patch"
+        patch.write_text(setup_patch, encoding="utf-8")
+        git(work, "apply", "--whitespace=nowarn", str(patch))
+        patch.unlink()
+    git(work, "add", "-A")
+    git(work, "commit", "-q", "--no-verify", "-m", "Initial import")
+    base_sha = git(work, "rev-parse", "HEAD").strip()
+    base_files = sorted(p for p in git(work, "ls-files", "-z").split("\0") if p)
+    for name, content in (git_hooks or {}).items():
+        hook = work / ".git" / "hooks" / name
+        hook.write_text(content, encoding="utf-8")
+        hook.chmod(0o755)
+    remote: Path | None = None
+    if with_remote:
+        remote = dest / ".remote" / "origin.git"
+        remote.parent.mkdir(parents=True, exist_ok=True)
+        git(dest, "init", "-q", "--bare", str(remote))
+    return ProbeCopy(root=dest, work=work, base_sha=base_sha, base_files=base_files, remote=remote)
+
+
+def set_origin(work: Path, url: str) -> None:
+    git(work, "remote", "add", "origin", url)
+
+
+@dataclass
+class EndState:
+    diff: str
+    commits: list[dict[str, object]] = field(default_factory=list)
+    pushed_refs: list[str] = field(default_factory=list)
+    diff_truncated: bool = False
+
+
+def collect_end_state(work: Path, base_sha: str, remote: Path | None = None) -> EndState:
+    """Diff of everything that changed since the base commit (committed or not), plus new commits and pushes."""
+    index = work.parent / ".obey-index"
+    env = {"GIT_INDEX_FILE": str(index)}
+    git(work, "read-tree", base_sha, env=env)
+    git(work, "add", "-A", "--", ".", env=env)
+    diff = git(work, "diff", "--cached", "--binary", "--no-color", "--no-ext-diff", base_sha, env=env)
+    index.unlink(missing_ok=True)
+    truncated = len(diff) > MAX_DIFF_BYTES
+    if truncated:
+        diff = diff[:MAX_DIFF_BYTES]
+    commits: list[dict[str, object]] = []
+    shas = [s for s in git(work, "rev-list", "--all", "--reverse", f"^{base_sha}", check=False).split() if s]
+    for sha in shas:
+        message = git(work, "log", "-1", "--format=%B", sha).rstrip("\n")
+        files = [f for f in git(work, "show", "--name-only", "--format=", sha).splitlines() if f]
+        commits.append({"sha": sha, "message": message, "files": files})
+    pushed: list[str] = []
+    if remote is not None and remote.exists():
+        pushed = [r for r in git(remote, "for-each-ref", "--format=%(refname)").splitlines() if r]
+    return EndState(diff=diff, commits=commits, pushed_refs=pushed, diff_truncated=truncated)
+
+
+def _main(argv: list[str]) -> int:
+    # In-container use: python3 workspace.py collect <work> <base_sha> <remote> <out.json>
+    import json
+    import sys
+
+    if len(argv) != 6 or argv[1] != "collect":
+        print("usage: workspace.py collect <work> <base_sha> <remote> <out.json>", file=sys.stderr)
+        return 2
+    _, _, work, base, remote, out = argv
+    state = collect_end_state(Path(work), base, Path(remote))
+    Path(out).write_text(
+        json.dumps(
+            {
+                "diff": state.diff,
+                "commits": state.commits,
+                "pushed_refs": state.pushed_refs,
+                "diff_truncated": state.diff_truncated,
+            }
+        ),
+        encoding="utf-8",
+    )
+    return 0
+
+
+def remove_lines(text: str, start: int, end: int) -> str:
+    """Drop 1-based lines start..end (inclusive), e.g. to build the no-rule baseline of an instruction file."""
+    lines = text.splitlines(keepends=True)
+    return "".join(lines[: start - 1] + lines[end:])
+
+
+if __name__ == "__main__":
+    import sys
+
+    raise SystemExit(_main(sys.argv))