co-agent-coder 0.1.0__py3-none-any.whl

coagent/gitx/durable.py

@@ -0,0 +1,147 @@
+"""Durable sync: get history off the VM after every checkpoint (FR-GIT-4).
+
+**A commit is not a checkpoint; the sync is.** `/content` is exactly the disk
+that disappears, so `checkpoint()` must run immediately after every commit:
+
+* `mode = "push"` — push `coagent/<id>` to a configured remote. Denied to any
+  other ref by the policy allowlist.
+* `mode = "bundle"` — write a `git bundle` to Drive (or any durable dir), with
+  no network at all. The first bundle carries full history; later ones are
+  `A..B` increments, so cost tracks the diff, not the repo.
+
+A failed sync must **warn and continue**: losing a checkpoint attempt is not
+worth stopping a task that is otherwise making progress (PRD FR-GIT-4).
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .git import GitError, GitRepo
+
+__all__ = ["SyncResult", "sync_push", "sync_bundle", "checkpoint"]
+
+
+@dataclass(slots=True)
+class SyncResult:
+    ok: bool
+    mode: str
+    message: str
+    ref: str = ""
+    path: Path | None = None
+    warnings: list[str] = field(default_factory=list)
+
+
+def sync_push(
+    repo: GitRepo,
+    remote: str,
+    branch: str,
+    *,
+    policy=None,
+    attempts: int = 2,
+) -> SyncResult:
+    """Push the session branch. Retries once, then reports rather than raises."""
+    last = ""
+    for attempt in range(1, attempts + 1):
+        try:
+            result = repo.push(remote, branch, policy=policy)
+        except GitError as exc:
+            # A denial or a missing token is not a transient failure: report it
+            # once and let the caller fall back to a bundle.
+            return SyncResult(ok=False, mode="push", message=str(exc), ref=branch)
+        if result.ok:
+            return SyncResult(ok=True, mode="push", message=f"pushed {branch} to {remote}", ref=branch)
+        last = (result.stderr or result.stdout).strip()[:500]
+        if attempt < attempts:
+            time.sleep(1.5)
+    return SyncResult(
+        ok=False,
+        mode="push",
+        message=f"push to {remote} failed: {last or 'unknown error'}",
+        ref=branch,
+    )
+
+
+def sync_bundle(
+    repo: GitRepo,
+    branch: str,
+    bundle_dir: str | Path,
+    *,
+    session_id: str,
+    previous_tip: str | None = None,
+) -> SyncResult:
+    """Write a bundle (full first, then incremental) and return its path."""
+    out_dir = Path(bundle_dir) / session_id
+    out_dir.mkdir(parents=True, exist_ok=True)
+    stamp = time.strftime("%Y%m%d-%H%M%S")
+    target = out_dir / f"{stamp}.bundle"
+
+    head = repo.head()
+    if previous_tip and repo.run(
+        "rev-parse", "--verify", "--quiet", f"{previous_tip}^{{commit}}", check=False
+    ).ok:
+        # Incremental: only the new commits. `^` makes it A..B (exclusive A).
+        spec = f"{previous_tip}..{branch}"
+        argv = ["bundle", "create", str(target), spec]
+    else:
+        argv = ["bundle", "create", str(target), "--all"]
+
+    result = repo.run(*argv, check=False)
+    if not result.ok:
+        return SyncResult(
+            ok=False,
+            mode="bundle",
+            message=f"git bundle failed: {result.stderr.strip()[:400]}",
+            ref=branch,
+        )
+    return SyncResult(
+        ok=True,
+        mode="bundle",
+        message=f"wrote bundle {target.name} ({target.stat().st_size / 1024:.0f} KB) at {head[:8]}",
+        ref=branch,
+        path=target,
+    )
+
+
+def checkpoint(
+    repo: GitRepo,
+    *,
+    branch: str,
+    session_id: str,
+    mode: str = "push",
+    remote: str = "origin",
+    bundle_dir: str | Path | None = None,
+    previous_tip: str | None = None,
+    policy=None,
+) -> SyncResult:
+    """Sync after a commit. Falls back to a bundle if the push fails."""
+    warnings: list[str] = []
+    if mode == "bundle":
+        if bundle_dir is None:
+            return SyncResult(
+                ok=False,
+                mode="bundle",
+                message="durability.mode is 'bundle' but no bundle_dir is configured; "
+                "mount Drive or set durability.bundle_dir.",
+                ref=branch,
+            )
+        return sync_bundle(
+            repo, branch, bundle_dir, session_id=session_id, previous_tip=previous_tip
+        )
+
+    pushed = sync_push(repo, remote, branch, policy=policy)
+    if pushed.ok:
+        return pushed
+    warnings.append(pushed.message)
+    if bundle_dir is None:
+        pushed.warnings = warnings
+        return pushed
+
+    # Fallback: checkpoint offline so the work survives eviction.
+    bundled = sync_bundle(repo, branch, bundle_dir, session_id=session_id, previous_tip=previous_tip)
+    bundled.warnings = warnings
+    if bundled.ok:
+        bundled.message = f"{pushed.message}; fell back to {bundled.message}"
+    return bundled

coagent/gitx/git.py

@@ -0,0 +1,351 @@
+"""A thin, jailed `git` runner.
+
+Every git call goes through here for four reasons:
+
+1. **No tokens in the environment.** The child gets a scrubbed env; credentials
+   arrive only through `GIT_ASKPASS`, never in a remote URL (DESIGN §9.2).
+2. **No accidental prompts.** `GIT_TERMINAL_PROMPT=0` turns a missing credential
+   into an error instead of a hang — a hang in a notebook looks like a freeze.
+3. **Machine-readable output.** `-z`/`--porcelain` everywhere, so parsing never
+   depends on locale or colour.
+4. **One place for the push allowlist** (FR-GIT-8): `push()` refuses any ref
+   outside `refs/heads/coagent/` and any unconfigured remote before spawn.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..safety.policy import Policy, Verdict
+
+__all__ = ["GitError", "GitRepo", "GitResult", "format_askpass_script"]
+
+
+class GitError(RuntimeError):
+    """A git command failed. Carries git's own stderr for the report."""
+
+    def __init__(self, message: str, *, argv: list[str] | None = None, stderr: str = "") -> None:
+        super().__init__(message)
+        self.argv = argv or []
+        self.stderr = stderr
+
+
+@dataclass(slots=True)
+class GitResult:
+    argv: list[str]
+    returncode: int
+    stdout: str
+    stderr: str
+
+    @property
+    def ok(self) -> bool:
+        return self.returncode == 0
+
+
+def format_askpass_script() -> str:
+    """A tiny POSIX `GIT_ASKPASS` helper that echoes the token from the env.
+
+    Written to `.coagent/tmp/askpass.sh` (mode 0700) instead of embedding the
+    token in the remote URL, which would persist in `.git/config`, appear in
+    `git remote -v`, and be captured in every Drive bundle.
+    """
+    return (
+        "#!/bin/sh\n"
+        "# coAgent credential helper. The token is read from the environment of the\n"
+        "# git child process only; it is never written to disk or to .git/config.\n"
+        'case "$1" in\n'
+        '  *Username*) printf \'%s\\n\' "${COAGENT_GIT_USERNAME:-x-access-token}" ;;\n'
+        '  *Password*) printf \'%s\\n\' "${COAGENT_GIT_TOKEN:-}" ;;\n'
+        '  *) printf \'%s\\n\' "${COAGENT_GIT_TOKEN:-}" ;;\n'
+        "esac\n"
+    )
+
+
+class GitRepo:
+    """Git operations scoped to one working tree."""
+
+    def __init__(
+        self,
+        root: str | Path,
+        *,
+        policy: Policy | None = None,
+        author_name: str = "coAgent",
+        author_email: str = "coagent@users.noreply.github.com",
+        token: str | None = None,
+        timeout_s: int = 120,
+    ) -> None:
+        self.root = Path(root).resolve()
+        self.policy = policy
+        self.author_name = author_name
+        self.author_email = author_email
+        self._token = token
+        self.timeout_s = timeout_s
+
+    # --------------------------------------------------------------- plumbing
+
+    def _env(self) -> dict[str, str]:
+        env = {k: v for k, v in os.environ.items() if "TOKEN" not in k.upper() and "SECRET" not in k.upper()}
+        env.update(
+            {
+                "GIT_TERMINAL_PROMPT": "0",
+                "GIT_AUTHOR_NAME": self.author_name,
+                "GIT_AUTHOR_EMAIL": self.author_email,
+                "GIT_COMMITTER_NAME": self.author_name,
+                "GIT_COMMITTER_EMAIL": self.author_email,
+                # Deterministic plumbing: no pager, no colour, no quoting.
+                "GIT_PAGER": "cat",
+                "PAGER": "cat",
+                "LC_ALL": "C",
+                # No pager/colour/quoting. Crucially we do NOT override
+                # core.autocrlf: whatever the machine and the repo already use
+                # is what the index was built with, and forcing a different
+                # value makes every CRLF file look permanently modified.
+            }
+        )
+        # Preserve the identity so `git commit` is attributable, but never the
+        # credential: that is injected per-call only for the ops that need it.
+        if self._token and self._askpass_path().exists():
+            env["GIT_ASKPASS"] = str(self._askpass_path())
+            env["COAGENT_GIT_TOKEN"] = self._token
+        return env
+
+    def _askpass_path(self) -> Path:
+        return self.root / ".coagent" / "tmp" / "askpass.sh"
+
+    def install_askpass(self) -> Path:
+        """Write the credential helper. Called once at bootstrap (DESIGN §11)."""
+        path = self._askpass_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(format_askpass_script(), encoding="utf-8")
+        with contextlib.suppress(OSError):  # Windows/ACL edge case
+            path.chmod(0o700)
+        return path
+
+    def run(self, *args: str, cwd: Path | None = None, check: bool = True) -> GitResult:
+        argv = ["git", *args]
+        proc = subprocess.run(
+            argv,
+            cwd=str(cwd or self.root),
+            env=self._env(),
+            capture_output=True,
+            text=True,
+            errors="replace",
+            timeout=self.timeout_s,
+        )
+        result = GitResult(argv=argv, returncode=proc.returncode, stdout=proc.stdout, stderr=proc.stderr)
+        if check and not result.ok:
+            raise GitError(
+                f"git {' '.join(args)} failed (exit {result.returncode}): {proc.stderr.strip()[:800]}",
+                argv=argv,
+                stderr=proc.stderr,
+            )
+        return result
+
+    # ------------------------------------------------------------------ state
+
+    def is_repo(self) -> bool:
+        return (self.root / ".git").exists() and self.run(
+            "rev-parse", "--git-dir", check=False
+        ).ok
+
+    def head(self) -> str:
+        return self.run("rev-parse", "HEAD").stdout.strip()
+
+    def current_branch(self) -> str:
+        return self.run("rev-parse", "--abbrev-ref", "HEAD").stdout.strip()
+
+    def branch_exists(self, name: str) -> bool:
+        return self.run("rev-parse", "--verify", "--quiet", f"refs/heads/{name}", check=False).ok
+
+    def remote_branch_exists(self, remote: str, name: str) -> bool:
+        return self.run(
+            "rev-parse", "--verify", "--quiet", f"refs/remotes/{remote}/{name}", check=False
+        ).ok
+
+    def remotes(self) -> list[str]:
+        out = self.run("remote", check=False).stdout
+        return [line.strip() for line in out.splitlines() if line.strip()]
+
+    def status_porcelain(self, *, ignore: tuple[str, ...] = ()) -> list[str]:
+        """Porcelain entries, optionally ignoring paths by prefix.
+
+        coAgent's own runtime state (`.coagent/lock.json`, `tmp/`, `sessions/`)
+        must not count as user dirt, or every session would refuse to start on
+        its own lock file.
+        """
+        out = self.run("status", "--porcelain=v1", "-z", "--untracked-files=all").stdout
+        entries = [entry for entry in out.split("\x00") if entry.strip()]
+        if not ignore:
+            return entries
+        kept: list[str] = []
+        for entry in entries:
+            path = entry[3:] if len(entry) > 3 else entry
+            if any(path == prefix or path.startswith(prefix) for prefix in ignore):
+                continue
+            kept.append(entry)
+        return kept
+
+    def is_dirty(self, *, ignore: tuple[str, ...] = ()) -> bool:
+        return bool(self.status_porcelain(ignore=ignore))
+
+    def changed_paths(self, *, ignore: tuple[str, ...] = ()) -> list[str]:
+        """Paths from porcelain entries, with the two-char status stripped."""
+        paths: list[str] = []
+        for entry in self.status_porcelain(ignore=ignore):
+            # Format: "XY <path>" (renames have an extra NUL-separated source).
+            path = entry[3:] if len(entry) > 3 else entry
+            if path:
+                paths.append(path)
+        return paths
+
+    def staged_paths(self) -> list[str]:
+        out = self.run("diff", "--cached", "--name-only", "-z").stdout
+        return [p for p in out.split("\x00") if p]
+
+    def has_staged_changes(self) -> bool:
+        return self.run("diff", "--cached", "--quiet", check=False).returncode == 1
+
+    def diff_stat(self, *, staged: bool = True) -> str:
+        args = ["diff", "--stat"] + (["--cached"] if staged else [])
+        return self.run(*args, check=False).stdout.strip()
+
+    def diff(self, *, staged: bool = True) -> str:
+        args = ["diff"] + (["--cached"] if staged else [])
+        return self.run(*args, check=False).stdout
+
+    # -------------------------------------------------------------- identity
+
+    def ensure_identity(self) -> None:
+        """Set user.name/user.email locally if unset — otherwise the first
+        commit fails and the whole session looks broken (DESIGN §11)."""
+        for key, value in (("user.name", self.author_name), ("user.email", self.author_email)):
+            current = self.run("config", "--get", key, check=False)
+            if not current.ok or not current.stdout.strip():
+                self.run("config", key, value)
+
+    # ------------------------------------------------------------------ write
+
+    def switch(self, branch: str, *, create: bool = False) -> None:
+        if create:
+            self.run("switch", "-c", branch)
+        else:
+            self.run("switch", branch)
+
+    def add(self, *paths: str) -> None:
+        self.run("add", "--", *paths)
+
+    def add_all_tracked(self) -> None:
+        """Stage modifications and deletions, but not untracked files."""
+        self.run("add", "-u")
+
+    def commit(self, message: str) -> str:
+        """Plain commit with a literal message (used mostly by tests)."""
+        self._commit_stdin(message if message.endswith("\n") else message + "\n")
+        return self.head()
+
+    def _scrub_commit_editor(self) -> None:
+        """Nothing to do; kept as the seam if a hooks policy is added later."""
+
+    def _commit_stdin(self, message: str, *, argv_extra: list[str] | None = None) -> None:
+        argv = ["git", "commit", "--no-verify", "--cleanup=verbatim", "-F", "-", *(argv_extra or [])]
+        proc = subprocess.run(
+            argv,
+            cwd=str(self.root),
+            env=self._env(),
+            input=message,
+            capture_output=True,
+            text=True,
+            errors="replace",
+            timeout=self.timeout_s,
+        )
+        if proc.returncode != 0:
+            raise GitError(
+                f"git commit failed (exit {proc.returncode}): {proc.stderr.strip()[:800]}",
+                argv=argv,
+                stderr=proc.stderr,
+            )
+
+    def commit_with_trailers(self, subject: str, body: str, trailers: list[tuple[str, str]]) -> str:
+        """Commit with a message built from a subject, body, and trailers.
+
+        Built in Python and passed via `-F -` on stdin so a trailer containing
+        newlines or quotes cannot break the argument list.
+        """
+        self._commit_stdin(build_commit_message(subject, body, trailers))
+        return self.head()
+
+    def log_oneline(self, *, grep: str = "", max_count: int = 20, rev: str = "HEAD") -> list[str]:
+        args = ["log", "--oneline", f"-n{max_count}"]
+        if grep:
+            args.append(f"--grep={grep}")
+        args.append(rev)
+        return [line for line in self.run(*args, check=False).stdout.splitlines() if line.strip()]
+
+    # ------------------------------------------------------------------- push
+
+    def push(self, remote: str, ref: str, *, policy: Policy | None = None) -> GitResult:
+        """Push one ref, after the allowlist check (FR-GIT-8)."""
+        active = policy or self.policy
+        if active is not None:
+            decision = active.check_push(remote, ref)
+            if decision.verdict is not Verdict.ALLOW:
+                raise GitError(f"push denied: {decision.reason} ({decision.rule})")
+        else:  # no policy configured: fall back to the narrow default
+            normalized = ref if ref.startswith("refs/") else f"refs/heads/{ref}"
+            if not normalized.startswith("refs/heads/coagent/"):
+                raise GitError(f"push denied: only coagent/* refs may be pushed, not {normalized}")
+        if not self._token:
+            raise GitError(
+                "no GitHub token is loaded; add one to Colab secrets to push. "
+                "Fall back to durability.mode = 'bundle' to checkpoint offline."
+            )
+        branch = ref.removeprefix("refs/heads/")
+        return self.run("push", "--set-upstream", remote, f"HEAD:refs/heads/{branch}", check=False)
+
+    def fetch(self, remote: str, *, depth: int | None = None) -> GitResult:
+        args = ["fetch", remote]
+        if depth:
+            args.append(f"--depth={depth}")
+        return self.run(*args, check=False)
+
+    def clone(self, url: str, dest: Path, *, depth: int = 1) -> None:
+        """Clone into `dest`. The URL must not carry credentials (DESIGN §9.2)."""
+        if "@" in url.split("://", 1)[-1].split("/", 1)[0]:
+            raise GitError(
+                "the clone URL contains embedded credentials. Use a bare https URL; "
+                "coAgent injects the token through GIT_ASKPASS instead."
+            )
+        argv = ["git", "clone", f"--depth={depth}", url, str(dest)]
+        proc = subprocess.run(
+            argv,
+            cwd=str(dest.parent),
+            env=self._env(),
+            capture_output=True,
+            text=True,
+            errors="replace",
+            timeout=max(self.timeout_s, 600),
+        )
+        if proc.returncode != 0:
+            raise GitError(
+                f"git clone failed (exit {proc.returncode}): {proc.stderr.strip()[:800]}",
+                argv=argv,
+                stderr=proc.stderr,
+            )
+
+
+def build_commit_message(subject: str, body: str, trailers: list[tuple[str, str]]) -> str:
+    """Subject, blank line, body, blank line, trailers — in that order.
+
+    `--cleanup=verbatim` keeps the trailers' exact spelling, which the
+    `--grep="Coagent-Step"` queries in the PRD depend on.
+    """
+    parts = [subject.strip()]
+    if body.strip():
+        parts.append(body.strip())
+    if trailers:
+        parts.append("\n".join(f"{key}: {value}" for key, value in trailers))
+    return "\n\n".join(parts) + "\n"

coagent/gitx/lock.py

@@ -0,0 +1,157 @@
+"""Single-writer session lock (PRD FR-GIT-6).
+
+`.coagent/lock.json` holds `{session_id, pid, started_at, heartbeat_at,
+expires_at, host}`. A live lock means a second session refuses; an expired one
+is stale and can be taken over. `--force` takes over even a live lock after
+reporting which session held it.
+
+This is advisory and deliberately simple: coAgent is a single-user tool, and a
+stateful lock protocol on an ephemeral VM is more failure modes than it buys.
+The real duplicate-work guard is that the session branch lives in git.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+__all__ = ["LockInfo", "SessionLock", "LockHeldError"]
+
+LOCK_RELPATH = Path(".coagent") / "lock.json"
+DEFAULT_TTL_S = 30 * 60
+
+
+class LockHeldError(RuntimeError):
+    """Another session holds the lock."""
+
+    def __init__(self, other: LockInfo) -> None:
+        self.other = other
+        minutes = max(0, int((other.expires_at - time.time()) / 60))
+        super().__init__(
+            f"session {other.session_id} holds the lock on this repo "
+            f"(host {other.host}, expires in {minutes} min). "
+            "Use --force to take over, or `coagent resume` to continue that session."
+        )
+
+
+@dataclass(slots=True)
+class LockInfo:
+    session_id: str
+    pid: int
+    host: str
+    started_at: float
+    heartbeat_at: float
+    expires_at: float
+
+    def is_expired(self, *, now: float | None = None) -> bool:
+        return (now or time.time()) >= self.expires_at
+
+    def same_process(self) -> bool:
+        """True when this lock is held by the current interpreter."""
+        return self.host == socket.gethostname() and self.pid == os.getpid()
+
+
+class SessionLock:
+    def __init__(self, repo_root: str | Path, session_id: str, *, ttl_s: int = DEFAULT_TTL_S) -> None:
+        self.root = Path(repo_root).resolve()
+        self.path = self.root / LOCK_RELPATH
+        self.session_id = session_id
+        self.ttl_s = ttl_s
+        self.info: LockInfo | None = None
+
+    # ------------------------------------------------------------------ read
+
+    def read(self) -> LockInfo | None:
+        if not self.path.exists():
+            return None
+        try:
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return None
+        required = set(LockInfo.__dataclass_fields__)
+        if not required <= set(data):
+            return None
+        return LockInfo(**{k: data[k] for k in required})
+
+    # ----------------------------------------------------------------- write
+
+    def acquire(self, *, force: bool = False) -> LockInfo:
+        existing = self.read()
+        if existing is not None and not existing.is_expired() and not existing.same_process() and not force:
+            # A live lock from another process/host blocks us unless forced.
+            raise LockHeldError(existing)
+        now = time.time()
+        info = LockInfo(
+            session_id=self.session_id,
+            pid=os.getpid(),
+            host=socket.gethostname(),
+            started_at=now,
+            heartbeat_at=now,
+            expires_at=now + self.ttl_s,
+        )
+        self._write(info)
+        self.info = info
+        return info
+
+    def heartbeat(self) -> LockInfo:
+        """Refresh the expiry. Called from the checkpoint loop (FR-REL-1)."""
+        current = self.read()
+        if current is not None and current.session_id != self.session_id:
+            raise LockHeldError(current)
+        base = current or (self.info or self._fresh())
+        now = time.time()
+        info = LockInfo(
+            session_id=self.session_id,
+            pid=os.getpid(),
+            host=socket.gethostname(),
+            started_at=base.started_at,
+            heartbeat_at=now,
+            expires_at=now + self.ttl_s,
+        )
+        self._write(info)
+        self.info = info
+        return info
+
+    def release(self) -> bool:
+        """Remove the lock, but never someone else's."""
+        current = self.read()
+        if current is None:
+            return False
+        if current.session_id != self.session_id and not current.is_expired():
+            return False
+        try:
+            self.path.unlink()
+        except OSError:
+            return False
+        self.info = None
+        return True
+
+    def __enter__(self) -> SessionLock:
+        self.acquire()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.release()
+
+    # ---------------------------------------------------------------- helpers
+
+    def _write(self, info: LockInfo) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self.path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(asdict(info), indent=2), encoding="utf-8")
+        os.replace(tmp, self.path)  # atomic on POSIX and Windows
+
+    def _fresh(self) -> LockInfo:
+        now = time.time()
+        return LockInfo(
+            session_id=self.session_id,
+            pid=os.getpid(),
+            host=socket.gethostname(),
+            started_at=now,
+            heartbeat_at=now,
+            expires_at=now + self.ttl_s,
+        )