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

coagent/gitx/log.py

@@ -0,0 +1,85 @@
+"""The session log: one JSONL record per turn (DESIGN §3.4, FR-TOL-8).
+
+Written per turn (not per session) because a preemption must not lose the tail.
+Every record is **redacted at write time** — redaction after the fact is a
+promise, redaction before the write is a property (PRD FR-PRV-3).
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ..safety.redact import Redactor
+
+__all__ = ["SessionLog", "LogRecord"]
+
+
+@dataclass(slots=True)
+class LogRecord:
+    step: int
+    phase: str
+    tool: str
+    ok: bool
+    tokens_in: int = 0
+    tokens_out: int = 0
+    ms: int = 0
+    commit: str = ""
+    args_hash: str = ""
+    error: str = ""
+    note: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        data: dict[str, Any] = {
+            "t": round(time.time(), 3),
+            "step": self.step,
+            "phase": self.phase,
+            "tool": self.tool,
+            "ok": self.ok,
+        }
+        if self.tokens_in or self.tokens_out:
+            data["tokens"] = {"in": self.tokens_in, "out": self.tokens_out}
+        if self.ms:
+            data["ms"] = self.ms
+        if self.commit:
+            data["commit"] = self.commit
+        if self.args_hash:
+            data["args_hash"] = self.args_hash
+        if self.error:
+            data["error"] = self.error
+        if self.note:
+            data["note"] = self.note
+        return data
+
+
+class SessionLog:
+    """Append-only JSONL log for one session."""
+
+    def __init__(self, repo_root: str | Path, session_id: str, *, redactor: Redactor | None = None) -> None:
+        self.path = Path(repo_root) / ".coagent" / "sessions" / f"{session_id}.jsonl"
+        self.redactor = redactor or Redactor()
+
+    def append(self, record: LogRecord) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        # Redact the serialised record: every string field, including nested ones.
+        safe = self.redactor.redact_obj(record.to_dict())
+        with self.path.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(safe, ensure_ascii=False) + "\n")
+
+    def tail(self, count: int = 20) -> list[dict[str, Any]]:
+        if not self.path.is_file():
+            return []
+        records: list[dict[str, Any]] = []
+        with self.path.open("r", encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    records.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+        return records[-count:]

coagent/gitx/resume.py

@@ -0,0 +1,199 @@
+"""Resume: rebuild a briefing from durable state (PRD FR-GIT-5, FR-REL-4).
+
+Deliberately **template extraction, not an LLM call** (DESIGN §3.4). A resume
+must be cheap and must work before the model is loaded, because the most common
+resume happens on a fresh VM after a preemption.
+
+Sources, in order of authority:
+
+1. the session branch and its `Coagent-*` trailers (always present);
+2. `.coagent/plans/*.md` (the memory that survives eviction);
+3. `.coagent/sessions/<id>.jsonl` (may be missing after a hard kill).
+
+If the log is missing, the briefing falls back to trailers — which is why the
+commit protocol matters more than the log.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .commit import parse_trailers
+from .git import GitRepo
+
+__all__ = ["Briefing", "build_briefing", "read_plan_items", "read_last_log_records"]
+
+
+@dataclass(slots=True)
+class PlanItem:
+    text: str
+    done: bool
+
+
+@dataclass(slots=True)
+class Briefing:
+    session_id: str
+    branch: str
+    last_commit: str = ""
+    last_subject: str = ""
+    trailers: dict[str, str] = field(default_factory=dict)
+    committed_steps: int = 0
+    max_step: int = 0
+    plan_path: Path | None = None
+    plan_items: list[PlanItem] = field(default_factory=list)
+    open_items: list[str] = field(default_factory=list)
+    recent: list[dict] = field(default_factory=list)
+    dirty_paths: list[str] = field(default_factory=list)
+    #: Committed artifacts from `artifacts/<run>/manifest.json` (§3.5). A resumed
+    #: VM has the files in git but no memory of them, so the briefing names them.
+    artifacts: list[str] = field(default_factory=list)
+
+    @property
+    def next_step(self) -> int:
+        """One past the highest step ever committed, not just HEAD's.
+
+        A plan or checkpoint commit can carry a lower `Coagent-Step` than the
+        last code commit; taking the max keeps step numbers monotonic, which is
+        what `git log --grep="Coagent-Step"` ordering depends on.
+        """
+        return self.max_step + 1
+
+    def render(self, *, max_chars: int = 1500) -> str:
+        """A 15-ish line briefing as plain text."""
+        lines = [
+            f"coAgent resume · session {self.session_id} · branch {self.branch}",
+            f"last commit: {self.last_commit[:8]} {self.last_subject}".rstrip(),
+            f"committed steps: {self.committed_steps} · next step: {self.next_step}",
+        ]
+        if self.trailers.get("Coagent-Task"):
+            lines.append(f"task: {self.trailers['Coagent-Task']}")
+        if self.trailers.get("Coagent-Verify"):
+            lines.append(f"last verify: {self.trailers['Coagent-Verify']}")
+        if self.dirty_paths:
+            lines.append(f"WARNING: uncommitted changes on disk: {', '.join(self.dirty_paths[:5])}")
+        if self.plan_path is not None:
+            lines.append(f"plan: {self.plan_path}")
+        if self.plan_items:
+            done = sum(1 for item in self.plan_items if item.done)
+            lines.append(f"plan progress: {done}/{len(self.plan_items)}")
+        for item in self.open_items[:8]:
+            lines.append(f"  [ ] {item}")
+        if self.artifacts:
+            shown = ", ".join(self.artifacts[:5])
+            more = f" (+{len(self.artifacts) - 5} more)" if len(self.artifacts) > 5 else ""
+            lines.append(f"artifacts: {shown}{more}")
+        if self.recent:
+            failures = [r for r in self.recent if not r.get("ok", True)]
+            if failures:
+                last = failures[-1]
+                lines.append(
+                    f"open failure: {last.get('tool', '?')} — "
+                    f"{str(last.get('error', ''))[:180]}"
+                )
+        text = "\n".join(lines)
+        if len(text) > max_chars:
+            text = text[: max_chars - 1] + "…"
+        return text
+
+
+def read_plan_items(plan_path: Path) -> list[PlanItem]:
+    """Parse `- [x]` / `- [ ]` checkboxes from a plan file."""
+    items: list[PlanItem] = []
+    try:
+        text = plan_path.read_text(encoding="utf-8")
+    except OSError:
+        return items
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith(("- [x]", "- [X]")):
+            items.append(PlanItem(text=stripped[5:].strip(), done=True))
+        elif stripped.startswith("- [ ]"):
+            items.append(PlanItem(text=stripped[5:].strip(), done=False))
+    return items
+
+
+def read_last_log_records(log_path: Path, *, count: int = 20) -> list[dict]:
+    """The last `count` JSONL records, tolerant of a truncated final line."""
+    if not log_path.is_file():
+        return []
+    records: list[dict] = []
+    try:
+        with log_path.open("r", encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    records.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue  # a kill can leave a partial line; skip it
+    except OSError:
+        return []
+    return records[-count:]
+
+
+def build_briefing(repo: GitRepo, session_id: str, branch: str) -> Briefing:
+    """Assemble the resume briefing from whatever survived."""
+    root = repo.root
+    briefing = Briefing(session_id=session_id, branch=branch)
+
+    log_out = repo.run("log", "--format=%H%x00%s%x00%B%x01", "-n50", branch, check=False)
+    commits = [c for c in log_out.stdout.split("\x01") if c.strip()]
+    briefing.committed_steps = sum(1 for c in commits if "Coagent-Step:" in c)
+    for commit in commits:
+        trailers = parse_trailers(commit)
+        try:
+            briefing.max_step = max(briefing.max_step, int(trailers.get("Coagent-Step", "0")))
+        except ValueError:
+            continue
+    if commits:
+        head = commits[0].split("\x00")
+        if len(head) >= 3:
+            briefing.last_commit = head[0].strip()
+            briefing.last_subject = head[1].strip()
+            briefing.trailers = parse_trailers(head[2])
+
+    # Plan: the newest plan file for this session, else the newest overall.
+    plan_dir = root / ".coagent" / "plans"
+    plan_path = None
+    if plan_dir.is_dir():
+        candidates = sorted(plan_dir.glob("*.md"), key=lambda p: p.stat().st_mtime, reverse=True)
+        if candidates:
+            plan_path = candidates[0]
+    if plan_path is not None:
+        briefing.plan_path = plan_path
+        briefing.plan_items = read_plan_items(plan_path)
+        briefing.open_items = [item.text for item in briefing.plan_items if not item.done]
+
+    briefing.recent = read_last_log_records(root / ".coagent" / "sessions" / f"{session_id}.jsonl")
+    briefing.artifacts = read_artifact_manifest(root, session_id)
+
+    if repo.is_dirty():
+        briefing.dirty_paths = repo.changed_paths()
+
+    return briefing
+
+
+def read_artifact_manifest(root: Path, session_id: str) -> list[str]:
+    """Committed artifact paths for a session, read straight from git's copy.
+
+    Deliberately tolerant: a missing or malformed manifest is not a reason to
+    refuse a resume. The briefing is best-effort, and the trailers already carry
+    the artifact list for the last commit.
+    """
+    import json
+
+    manifest = root / "artifacts" / session_id / "manifest.json"
+    if not manifest.is_file():
+        return []
+    try:
+        data = json.loads(manifest.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return []
+    paths: list[str] = []
+    for entry in data.get("artifacts", []):
+        if isinstance(entry, dict) and entry.get("path"):
+            paths.append(str(entry["path"]))
+    return paths

coagent/gitx/session.py

@@ -0,0 +1,233 @@
+"""Session lifecycle: clone, guard, branch (PRD FR-GIT-1/2, FR-GIT-5).
+
+A session is identified by its branch: `coagent/<yyyy-mm-dd>-<short-id>`. If the
+branch already exists, opening it is a *resume*, not a new session — that is the
+whole recovery story from DESIGN §3.6.
+
+Two guards the tests care about:
+
+* **Refuse a dirty tree.** A user with uncommitted work must get a stop with
+  instructions, never a reset (FR-GIT-1, AT-3).
+* **Never touch `main`.** The session branch is created from `HEAD` and the
+  session refuses to run on a branch outside the coagent namespace.
+"""
+
+from __future__ import annotations
+
+import secrets
+import shutil
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+from .git import GitError, GitRepo
+from .lock import SessionLock
+
+__all__ = [
+    "Session",
+    "SessionError",
+    "DirtyTreeError",
+    "new_session_id",
+    "open_session",
+    "short_id",
+    "SESSION_BRANCH_PREFIX",
+]
+
+SESSION_BRANCH_PREFIX = "coagent/"
+SHORT_ID_LEN = 6
+
+# coAgent's own ephemeral state. Never counted as user dirt.
+COAGENT_RUNTIME_PATHS: tuple[str, ...] = (
+    ".coagent/lock.json",
+    ".coagent/tmp/",
+    ".coagent/sessions/",
+    ".coagent/cache/",
+    ".coagent/bundles/",
+    # Plans are coAgent's own memory. Leaving them out would make every re-run
+    # refuse to start on coAgent's own leftovers.
+    ".coagent/plans/",
+    ".coagent/secrets",
+)
+
+
+class SessionError(RuntimeError):
+    """The session could not be opened. The message is the user's next step."""
+
+
+class DirtyTreeError(SessionError):
+    """The working tree has uncommitted changes; coAgent refuses to clobber them."""
+
+    def __init__(self, paths: list[str]) -> None:
+        listed = "\n  ".join(paths[:20])
+        more = f"\n  … and {len(paths) - 20} more" if len(paths) > 20 else ""
+        super().__init__(
+            "the working tree has uncommitted changes, so coAgent will not start "
+            "(it never resets your work). Commit, stash, or discard them first:\n"
+            f"  {listed}{more}\n"
+            "Then re-run. Nothing has been modified."
+        )
+        self.paths = paths
+
+
+def short_id(n: int = SHORT_ID_LEN) -> str:
+    return secrets.token_hex(max(3, n // 2))[:n]
+
+
+def new_session_id(*, now: datetime | None = None, short: str | None = None) -> str:
+    """`2026-11-12-a1b2c3` — date first so branches sort chronologically."""
+    moment = now or datetime.now(UTC)
+    return f"{moment:%Y-%m-%d}-{short or short_id()}"
+
+
+@dataclass(slots=True)
+class Session:
+    """An open working session: repo, branch, lock, identity."""
+
+    repo: GitRepo
+    session_id: str
+    branch: str
+    resumed: bool = False
+    lock: SessionLock | None = None
+
+    @property
+    def root(self) -> Path:
+        return self.repo.root
+
+    def checkpoint_heartbeat(self) -> None:
+        if self.lock is not None:
+            self.lock.heartbeat()
+
+    def close(self, *, release_lock: bool = True) -> None:
+        if release_lock and self.lock is not None:
+            self.lock.release()
+            self.lock = None
+
+
+def _ensure_coagent_ignored(root: Path) -> None:
+    """Warn (never silently edit) when `.coagent/` runtime state is untracked.
+
+    coAgent writes `.coagent/lock.json`, `tmp/`, and `sessions/`; a user repo
+    without these ignores would see a permanently dirty tree and refuse to
+    start its own session. DESIGN §11 is explicit that bootstrap **warns**
+    rather than mutating a tracked file, so we record the advice on the session
+    and leave the file alone.
+    """
+    ignore = root / ".gitignore"
+    needed = (".coagent/lock.json", ".coagent/tmp/", ".coagent/sessions/")
+    try:
+        existing = ignore.read_text(encoding="utf-8") if ignore.is_file() else ""
+    except OSError:
+        return
+    missing = [p for p in needed if p not in existing]
+    if missing:
+        # Docker-style: report once, do not surprise the user by editing a file
+        # that is already in their history.
+        import sys
+
+        print(
+            "coagent: warning — .gitignore does not ignore coAgent runtime state:\n"
+            + "\n".join(f"  {p}" for p in missing)
+            + "\n  Add them, or `coagent init` will keep reporting a dirty tree.",
+            file=sys.stderr,
+        )
+
+
+def open_session(
+    repo_path: str | Path,
+    *,
+    session_id: str | None = None,
+    branch: str | None = None,
+    force: bool = False,
+    author_name: str = "coAgent",
+    author_email: str = "coagent@users.noreply.github.com",
+    token: str | None = None,
+    ttl_s: int = 30 * 60,
+    allow_branch: str | None = None,
+) -> Session:
+    """Open (or resume) a coAgent session on an existing clone.
+
+    `allow_branch` exists for tests and for the `durable` clone path; in normal
+    use the branch must live under `coagent/`.
+    """
+    root = Path(repo_path).resolve()
+    if not root.is_dir():
+        raise SessionError(f"{root} is not a directory.")
+    repo = GitRepo(root, author_name=author_name, author_email=author_email, token=token)
+    if not repo.is_repo():
+        raise SessionError(
+            f"{root} is not a git repository. Clone it first, or pass a repo URL to coAgent(repo=...)."
+        )
+
+    repo.ensure_identity()
+    _ensure_coagent_ignored(root)
+
+    # Guard: never start on top of the user's uncommitted work. coAgent's own
+    # runtime state is excluded (DESIGN §11: warn, never mutate a tracked file).
+    if repo.is_dirty(ignore=COAGENT_RUNTIME_PATHS):
+        raise DirtyTreeError(repo.changed_paths(ignore=COAGENT_RUNTIME_PATHS))
+
+    current = repo.current_branch()
+
+    if branch is not None:
+        target = branch
+    elif current.startswith(SESSION_BRANCH_PREFIX):
+        # Already on a session branch: this is a resume.
+        target = current
+    else:
+        target = f"{SESSION_BRANCH_PREFIX}{session_id or new_session_id()}"
+
+    resumed = repo.branch_exists(target)
+
+    if not resumed:
+        try:
+            repo.switch(target, create=True)
+        except GitError as exc:
+            raise SessionError(
+                f"could not create the session branch {target}: {exc}. "
+                "If you started from a detached HEAD, check out a branch first."
+            ) from exc
+    else:
+        if current != target:
+            try:
+                repo.switch(target)
+            except GitError as exc:
+                raise SessionError(f"could not switch to the existing session branch {target}: {exc}") from exc
+
+    if allow_branch is None and not target.startswith(SESSION_BRANCH_PREFIX):
+        raise SessionError(
+            f"refusing to work on {target!r}: coAgent only works on {SESSION_BRANCH_PREFIX}* "
+            "branches so that main is never touched."
+        )
+
+    sid = target.removeprefix(SESSION_BRANCH_PREFIX)
+    lock = SessionLock(root, sid, ttl_s=ttl_s)
+    lock.acquire(force=force)
+
+    return Session(repo=repo, session_id=sid, branch=target, resumed=resumed, lock=lock)
+
+
+def clone_repo(
+    url: str,
+    dest: str | Path,
+    *,
+    depth: int = 1,
+    token: str | None = None,
+    author_name: str = "coAgent",
+    author_email: str = "coagent@users.noreply.github.com",
+    overwrite: bool = False,
+) -> GitRepo:
+    """Clone `url` into `dest` (`--depth 1` by default, DESIGN §3.1)."""
+    target = Path(dest).resolve()
+    if target.exists() and any(target.iterdir()):
+        if not overwrite:
+            raise SessionError(
+                f"{target} already exists and is not empty. coAgent will not overwrite it; "
+                "pass overwrite=True to replace it, or point at a different directory."
+            )
+        shutil.rmtree(target)
+    target.parent.mkdir(parents=True, exist_ok=True)
+
+    repo = GitRepo(target, author_name=author_name, author_email=author_email, token=token)
+    repo.install_askpass()
+    repo.clone(url, target, depth=depth)
+    return repo

coagent/llm/__init__.py

@@ -0,0 +1,83 @@
+"""The model layer: one interface, a local 4-bit backend, and a scripted fake.
+
+`import coagent.llm` must stay torch-free. `make_backend()` is the only place
+that reaches for `transformers`, and it does so lazily.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .base import (
+    BudgetError,
+    FakeBackend,
+    GenerationConfig,
+    GenerationResult,
+    LLMBackend,
+    Message,
+    StopReason,
+    TokenBudget,
+    Usage,
+)
+from .grammar import (
+    Envelope,
+    EnvelopeError,
+    extract_json_candidates,
+    looks_like_final_answer,
+    parse_envelope,
+    repair_json,
+    strip_fences,
+)
+from .registry import (
+    MODELS,
+    T4_COMPUTE_CAPABILITY,
+    T4_MIN_VRAM_GB,
+    ModelSpec,
+    PreflightResult,
+    get_model,
+    get_model_by_name,
+    preflight_gpu,
+)
+
+__all__ = [
+    "MODELS",
+    "T4_COMPUTE_CAPABILITY",
+    "T4_MIN_VRAM_GB",
+    "BudgetError",
+    "Envelope",
+    "EnvelopeError",
+    "FakeBackend",
+    "GenerationConfig",
+    "GenerationResult",
+    "LLMBackend",
+    "Message",
+    "ModelSpec",
+    "PreflightResult",
+    "StopReason",
+    "TokenBudget",
+    "Usage",
+    "extract_json_candidates",
+    "get_model",
+    "get_model_by_name",
+    "looks_like_final_answer",
+    "make_backend",
+    "parse_envelope",
+    "preflight_gpu",
+    "repair_json",
+    "strip_fences",
+]
+
+
+def make_backend(kind: str = "transformers", **kwargs: Any) -> LLMBackend:
+    """Construct a backend by name.
+
+    `kind="fake"` is the test/`--dry-run` path; `kind="transformers"` imports the
+    GPU stack only when it is actually used.
+    """
+    if kind == "fake":
+        return FakeBackend(**kwargs)
+    if kind == "transformers":
+        from .transformers_backend import TransformersBackend
+
+        return TransformersBackend(**kwargs)
+    raise ValueError(f"unknown backend {kind!r}; expected 'transformers' or 'fake'")