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

coagent/safety/policy.py

@@ -0,0 +1,219 @@
+"""Policy: the approval matrix, enforced in code (PRD FR-TOL-4, DESIGN §9.1).
+
+Two things live here:
+
+* `SafetyClass` — how a tool is classified (read / write / exec / vcs / ui).
+* `Policy.decide()` — the one function that answers "may this run?".
+
+Rules, in order (deny before allow, per FR-GIT-9):
+
+1. A denylisted command is denied, always.
+2. `git push` to a ref outside `git.push_ref_prefix`, or to an unconfigured
+   remote, is denied.
+3. Reads inside the jail are allowed.
+4. Writes inside the repo on the session branch are allowed.
+5. Everything in `require_approval` asks in interactive mode and is **denied**
+   in non-interactive mode. The default flips to deny, not allow.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .denylist import DEFAULT_DENIED, Denial, deny_reasons
+
+__all__ = [
+    "Decision",
+    "Policy",
+    "RiskClass",
+    "SafetyClass",
+    "Verdict",
+]
+
+
+class SafetyClass(str, enum.Enum):
+    """How a tool is classified for the approval matrix."""
+
+    READ = "read"
+    WRITE = "write"
+    EXEC = "exec"
+    VCS = "vcs"
+    UI = "ui"
+
+
+class RiskClass(str, enum.Enum):
+    """The action classes named in config `[safety] require_approval`."""
+
+    NETWORK = "network"
+    INSTALL = "install"
+    DELETE = "delete"
+    WRITE_OUTSIDE_REPO = "write_outside_repo"
+
+
+class Verdict(str, enum.Enum):
+    ALLOW = "allow"
+    ASK = "ask"
+    DENY = "deny"
+
+
+@dataclass(frozen=True, slots=True)
+class Decision:
+    verdict: Verdict
+    reason: str
+    rule: str = ""
+
+    @property
+    def allowed(self) -> bool:
+        return self.verdict is Verdict.ALLOW
+
+    @property
+    def needs_approval(self) -> bool:
+        return self.verdict is Verdict.ASK
+
+
+@dataclass
+class Policy:
+    """The session's enforcement state."""
+
+    repo_root: Path
+    interactive: bool = True
+    allow_read: list[Path] = field(default_factory=list)
+    push_ref_prefix: str = "refs/heads/coagent/"
+    allowed_remotes: tuple[str, ...] = ("origin",)
+    require_approval: tuple[str, ...] = (
+        RiskClass.NETWORK.value,
+        RiskClass.INSTALL.value,
+        RiskClass.DELETE.value,
+        RiskClass.WRITE_OUTSIDE_REPO.value,
+    )
+    deny_rules: tuple[str, ...] = DEFAULT_DENIED
+    # Origins allowed to every write: the repo and the ephemeral scratch dir.
+    scratch: Path | None = None
+
+    def __post_init__(self) -> None:
+        self.repo_root = Path(self.repo_root).resolve()
+        self.allow_read = [Path(p).resolve() for p in self.allow_read]
+        if self.scratch is not None:
+            self.scratch = Path(self.scratch).resolve()
+
+    # ------------------------------------------------------------------ reads
+
+    def check_read(self, path: Path) -> Decision:
+        """Reads are jailed too (DESIGN §6.2) — after `mount_drive` an unjailed
+        read is access to the user's entire Drive."""
+        resolved = Path(path).resolve()
+        if self._inside(resolved, self.repo_root):
+            if ".git" in resolved.relative_to(self.repo_root).parts:
+                # .git is not readable through read_file; git tools open it directly.
+                return Decision(Verdict.DENY, "reading .git through the file tools is not allowed", "git-internal")
+            return Decision(Verdict.ALLOW, "inside the repo", "read-in-jail")
+        if self.scratch and self._inside(resolved, self.scratch):
+            return Decision(Verdict.ALLOW, "inside the scratch dir", "read-scratch")
+        for extra in self.allow_read:
+            if self._inside(resolved, extra):
+                return Decision(Verdict.ALLOW, "inside an allow_read entry", "read-allowed")
+        return Decision(
+            Verdict.DENY,
+            f"{resolved} is outside the repo jail; add it to [tools] allow_read to permit it",
+            "read-outside-jail",
+        )
+
+    # ----------------------------------------------------------------- writes
+
+    def check_write(self, path: Path) -> Decision:
+        resolved = Path(path).resolve()
+        if self._inside(resolved, self.repo_root):
+            return Decision(Verdict.ALLOW, "inside the repo on the session branch", "write-in-repo")
+        if self.scratch and self._inside(resolved, self.scratch):
+            return Decision(Verdict.ALLOW, "inside the scratch dir", "write-scratch")
+        return self._risk(
+            RiskClass.WRITE_OUTSIDE_REPO,
+            f"{resolved} is outside the repo; writing there needs approval",
+            "write-outside-repo",
+        )
+
+    # ------------------------------------------------------------------ shell
+
+    def check_shell(self, cmd: str) -> Decision:
+        denial: Denial | None = next(iter(deny_reasons(cmd, self.deny_rules)), None)
+        if denial is not None:
+            return Decision(Verdict.DENY, denial.reason, f"deny:{denial.rule}")
+        if _is_delete(cmd):
+            return self._risk(RiskClass.DELETE, "delete/move/chmod needs approval", "exec-delete")
+        if _is_install(cmd):
+            return self._risk(RiskClass.INSTALL, "installing packages needs approval", "exec-install")
+        if _is_network(cmd):
+            return self._risk(RiskClass.NETWORK, "network access needs approval", "exec-network")
+        return Decision(Verdict.ALLOW, "shell command", "exec-allow")
+
+    # -------------------------------------------------------------------- git
+
+    def check_push(self, remote: str, ref: str) -> Decision:
+        """Only configured remotes, only coagent/* refs (FR-GIT-8)."""
+        if remote not in self.allowed_remotes:
+            return Decision(
+                Verdict.DENY,
+                f"remote {remote!r} is not in [git] remotes {list(self.allowed_remotes)}",
+                "push-remote",
+            )
+        normalized = ref if ref.startswith("refs/") else f"refs/heads/{ref}"
+        if not normalized.startswith(self.push_ref_prefix):
+            return Decision(
+                Verdict.DENY,
+                f"only {self.push_ref_prefix}* may be pushed, not {normalized}",
+                "push-ref",
+            )
+        return Decision(Verdict.ALLOW, "checkpoint push to the session branch", "push-session")
+
+    # ------------------------------------------------------------------ help
+
+    def _risk(self, risk: RiskClass, why: str, rule: str) -> Decision:
+        if risk.value in self.require_approval:
+            if self.interactive:
+                return Decision(Verdict.ASK, why, rule)
+            return Decision(Verdict.DENY, f"{why} (non-interactive mode defaults to deny)", rule)
+        return Decision(Verdict.ALLOW, why, rule)
+
+    @staticmethod
+    def _inside(path: Path, root: Path) -> bool:
+        try:
+            path.relative_to(root)
+        except ValueError:
+            return False
+        return True
+
+
+_INSTALL_HINTS = ("pip install", "pip3 install", "apt-get", "apt ", "conda install", "npm install", "uv pip")
+_NETWORK_HINTS = (
+    "curl",
+    "wget",
+    "git clone",
+    "git fetch",
+    "git pull",
+    "requests.get",
+    "http://",
+    "https://",
+    "huggingface-cli download",
+)
+_DELETE_HINTS = ("rm ", "rmdir", "mv ", "chmod", "chown", "unlink", "shutil.rmtree")
+
+
+def _first_word(cmd: str) -> str:
+    return cmd.strip().split(maxsplit=1)[0] if cmd.strip() else ""
+
+
+def _is_install(cmd: str) -> bool:
+    return any(hint in cmd for hint in _INSTALL_HINTS)
+
+
+def _is_network(cmd: str) -> bool:
+    word = _first_word(cmd)
+    if word in {"curl", "wget", "ssh", "scp", "nc"}:
+        return True
+    return any(hint in cmd for hint in _NETWORK_HINTS)
+
+
+def _is_delete(cmd: str) -> bool:
+    return any(hint in cmd for hint in _DELETE_HINTS)

coagent/safety/redact.py

@@ -0,0 +1,146 @@
+"""Secret redaction (PRD FR-PRV-2 / FR-BOOT-5).
+
+Redaction happens *before* a string reaches a log, a display, a report, or a
+committed file. Every entry point that writes text goes through `redact()`.
+
+The output keeps the last four characters so a log stays useful for "which
+token was that" without being usable as a credential.
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = ["MASK", "Redactor", "redact", "redact_obj", "contains_secret", "SECRET_PATTERNS"]
+
+MASK = "•••"
+
+# Ordered most-specific first. Each entry is (label, compiled pattern, group).
+# The group selects the value to redact when the overall match includes context.
+_PATTERNS: list[tuple[str, re.Pattern[str], int]] = [
+    # Fine-grained GitHub PATs: github_pat_11ABCDEFG0abc...
+    ("github_pat_fine", re.compile(r"github_pat_[A-Za-z0-9_]{20,}"), 0),
+    # Classic PATs and OAuth tokens.
+    ("github_pat", re.compile(r"\bgh[pousr]_[A-Za-z0-9]{16,}"), 0),
+    # Hugging Face
+    ("hf_token", re.compile(r"\bhf_[A-Za-z0-9]{16,}"), 0),
+    # OpenAI-style
+    ("openai", re.compile(r"\bsk-[A-Za-z0-9_\-]{16,}"), 0),
+    # Anthropic
+    ("anthropic", re.compile(r"\bsk-ant-[A-Za-z0-9_\-]{16,}"), 0),
+    # AWS access key id
+    ("aws_key", re.compile(r"\bAKIA[0-9A-Z]{16}\b"), 0),
+    # Google API key: AIza + 35 chars (case-sensitive alphabet)
+    ("google_api", re.compile(r"\bAIza[0-9A-Za-z_\-]{30,40}\b"), 0),
+    # Slack
+    ("slack", re.compile(r"\bxox[baprs]-[A-Za-z0-9\-]{10,}"), 0),
+    # Stripe
+    ("stripe", re.compile(r"\bsk_(?:live|test)_[A-Za-z0-9]{16,}"), 0),
+    # JWT: three base64url segments, the first of which decodes to {"alg":...
+    ("jwt", re.compile(r"\beyJ[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}"), 0),
+    # Credentials embedded in a URL (https://user:token@host) — clone URLs leak
+    # into .git/config and remote -v output.
+    ("url_credentials", re.compile(r"(://)[^/\s:@]+:[^/\s@]+(@)"), 2),
+    # Bearer / token headers in captured output.
+    ("bearer", re.compile(r"(?i)\b(?:bearer|token)\s+([A-Za-z0-9._\-]{16,})"), 1),
+    # Private key blocks.
+    (
+        "private_key",
+        re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----.*?-----END [A-Z ]*PRIVATE KEY-----", re.S),
+        0,
+    ),
+    # Key=value assignments for known secret-ish names, e.g. GH_TOKEN=ghp_...
+    (
+        "assigned_secret",
+        re.compile(
+            r"(?i)\b([A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|PASSWD|API_KEY|APIKEY|CREDENTIAL)[A-Z0-9_]*)"
+            r"\s*[=:]\s*[\"']?([^\s\"',}]{8,})"
+        ),
+        2,
+    ),
+]
+
+SECRET_PATTERNS = tuple(label for label, _, _ in _PATTERNS)
+
+
+def _mask_value(value: str) -> str:
+    """`MASK` plus the last 4 characters, never the first."""
+    tail = value[-4:] if len(value) > 8 else ""
+    return f"{MASK}{tail}"
+
+
+class Redactor:
+    """A reusable redactor with a set of literal secrets known for this session.
+
+    Registering a token means it is removed even when it does not match any
+    pattern — e.g. a short PAT pasted from a different provider.
+    """
+
+    __slots__ = ("_literals",)
+
+    def __init__(self, literals: list[str] | None = None) -> None:
+        self._literals: list[str] = [s for s in (literals or []) if s and len(s) >= 8]
+
+    def add(self, secret: str | None) -> None:
+        if secret and len(secret) >= 8 and secret not in self._literals:
+            self._literals.append(secret)
+        # Longest first so a token that contains another redacts as one unit.
+        self._literals.sort(key=len, reverse=True)
+
+    def redact(self, text: str) -> str:
+        if not text:
+            return text
+        for literal in self._literals:
+            if literal in text:
+                text = text.replace(literal, _mask_value(literal))
+        for _label, pattern, group in _PATTERNS:
+            text = pattern.sub(lambda m, g=group: _replace(m, g), text)
+        return text
+
+    def redact_obj(self, obj: object) -> object:
+        return _walk(obj, self.redact)
+
+    def contains_secret(self, text: str) -> bool:
+        """True if redaction would change `text` — used by the leak tests."""
+        return self.redact(text) != text
+
+
+def _replace(match: re.Match[str], group: int) -> str:
+    whole = match.group(0)
+    if group == 0:
+        return whole[:0] + _mask_value(whole)
+    start, end = match.span(group)
+    offset = match.start()
+    rel_start, rel_end = start - offset, end - offset
+    return whole[:rel_start] + _mask_value(whole[rel_start:rel_end]) + whole[rel_end:]
+
+
+_DEFAULT = Redactor()
+
+
+def redact(text: str) -> str:
+    """Redact using the default pattern set."""
+    return _DEFAULT.redact(text)
+
+
+def redact_obj(obj: object) -> object:
+    """Recursively redact strings inside dicts/lists/tuples."""
+    return _DEFAULT.redact_obj(obj)
+
+
+def contains_secret(text: str) -> bool:
+    return _DEFAULT.contains_secret(text)
+
+
+def _walk(obj: object, fn) -> object:
+    if isinstance(obj, str):
+        return fn(obj)
+    if isinstance(obj, dict):
+        return {fn(k) if isinstance(k, str) else k: _walk(v, fn) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_walk(v, fn) for v in obj]
+    if isinstance(obj, tuple):
+        return tuple(_walk(v, fn) for v in obj)
+    if isinstance(obj, set):
+        return {_walk(v, fn) for v in obj}
+    return obj

coagent/templates/config.toml

@@ -0,0 +1,104 @@
+# coAgent configuration — committed to your repo so a session is reproducible
+# on any VM. See DESIGN.md §11 and PRD.md Appendix A.
+#
+# Bump `schema_version` only when this file's structure changes incompatibly;
+# coAgent refuses to run against a newer schema than it understands.
+
+schema_version = 1
+
+[model]
+# The only validated configuration on a free T4 (PRD FR-MDL-1).
+name = "Qwen/Qwen2.5-Coder-7B-Instruct"
+# nf4 = bitsandbytes 4-bit; compute dtype is fp16 because T4 (SM 7.5) has no bf16.
+quant = "nf4"
+# Hard cap, counted with the model's own tokenizer (PRD D2 / FR-MDL-2).
+max_context = 12288
+max_new_tokens = 1024
+# Sampling: deterministic for edits, warmer for planning (FR-MDL-4).
+temperature_edit = 0.2
+temperature_plan = 0.7
+top_p = 0.95
+# Per-session seed, logged for reproducibility. 0 = pick a random seed and log it.
+seed = 0
+# Optional outlines-envelope constrained decoding (DESIGN §4.3). Off by default;
+# the tolerant-parse path must stay functional when this is disabled.
+constrained = false
+# Fallback used only after the OOM ladder fails to fit the default model (PRD D6).
+fallback_name = "Qwen/Qwen2.5-Coder-3B-Instruct"
+fallback_max_context = 8192
+
+[verify]
+# Run with CUDA_VISIBLE_DEVICES="" so tests never fight the model for VRAM (PRD D4).
+commands = ["ruff check .", "pytest -q"]
+# Run at most once per task, after the model yields the GPU (DESIGN §4.6).
+gpu_commands = []
+timeout_s = 300
+# Free VRAM required before a gpu_commands step is allowed to start.
+vram_reserve_mb = 1024
+# A feature without a test is not done (FR-VER-5).
+require_tests = true
+# Failures fed back to the model are reduced to names + traceback tails (FR-VER-3).
+feedback_max_tokens = 1500
+
+[git]
+author_name = "coAgent"
+author_email = "coagent@users.noreply.github.com"
+# Only these remotes may receive a push. Add "durable" when origin is public
+# so WIP history does not leak (DESIGN §3.1, PRD R7).
+remotes = ["origin"]
+clone_depth = 1
+# Ref namespace coAgent is allowed to push. main is never writable (FR-GIT-8).
+push_ref_prefix = "refs/heads/coagent/"
+
+[durability]
+# push = push the session branch; bundle = write git bundles to Drive (offline).
+mode = "push"
+remote = "origin"
+# Checkpoint at least this often while the tree is dirty (FR-REL-1).
+heartbeat_s = 180
+
+[agent]
+max_steps = 60
+max_wall_s = 2700
+max_tokens = 200000
+max_gpu_min = 40
+max_commits = 40
+max_consecutive_failures = 3
+# Loop detection thresholds on the state fingerprint (FR-AGT-6).
+replan_after_repeats = 3
+stop_after_repeats = 5
+
+[tools]
+# Repo root is always readable. Add e.g. "/content/data" to extend the read jail.
+allow_read = []
+# Combined stdout+stderr cap before head/tail truncation.
+max_output_bytes = 65536
+shell_timeout_s = 120
+notebook_timeout_s = 300
+
+[artifacts]
+commit_under_mb = 5
+store = "drive"
+drive_dir = "coagent/artifacts"
+
+[safety]
+# Risky action classes that need a human click in interactive mode.
+# In non-interactive mode these flip to deny (DESIGN §9.1).
+require_approval = ["network", "install", "delete", "write_outside_repo"]
+# Evaluated before allow rules, so force-push stays denied even on coagent/*.
+deny = [
+  "git push --force",
+  "git push -f",
+  "git push origin main",
+  "git reset --hard",
+  "git branch -D",
+  "rm -rf /",
+  "chmod -R 777 /",
+]
+
+[ui]
+# show = render the notebook chat UI; headless = no widgets (CLI/tests).
+mode = "show"
+# Optional Gradio surface behind the Colab port proxy (P1, never required).
+gradio = false
+gradio_port = 7860

coagent/tools/__init__.py

@@ -0,0 +1,155 @@
+"""Tool packages, assembled per phase (DESIGN §7.1).
+
+`build_registry()` returns the tools available for a phase. Phases exist because
+a small model does one job well: SURVEY can only read, PLAN cannot write at all,
+ACT gets one write or exec, VERIFY may only run checks.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..config import Config
+from ..context.artifacts import ArtifactStore
+from ..safety.denylist import DEFAULT_DENIED
+from ..safety.policy import Policy, SafetyClass
+from .artifacts import DisplayArtifactTool, SaveArtifactTool
+from .base import ArgSpec, BaseTool, ToolError, ToolRegistry, ToolResult, ToolSchemaError
+from .fs import (
+    EditFileTool,
+    FileSession,
+    GrepTool,
+    ListDirTool,
+    ReadFileTool,
+    WriteFileTool,
+    apply_search_replace,
+    truncate_head_tail,
+)
+from .notebooks import EditNotebookTool, ExecNotebookTool, ReadNotebookTool
+from .shell import ExecConfig, RunPythonTool, RunShellTool, RunTestsTool
+
+__all__ = [
+    "ArgSpec",
+    "ArtifactStore",
+    "BaseTool",
+    "ExecConfig",
+    "FileSession",
+    "Phase",
+    "ToolError",
+    "ToolRegistry",
+    "ToolResult",
+    "ToolSchemaError",
+    "apply_search_replace",
+    "build_policy",
+    "build_registry",
+    "truncate_head_tail",
+]
+
+# What each phase is allowed to do. PLAN is absent on purpose: it cannot act.
+PHASE_SAFETY: dict[str, frozenset[SafetyClass]] = {
+    "survey": frozenset({SafetyClass.READ}),
+    "plan": frozenset(),
+    "act": frozenset(
+        {SafetyClass.READ, SafetyClass.WRITE, SafetyClass.EXEC, SafetyClass.VCS, SafetyClass.UI}
+    ),
+    # VERIFY may render a plot it just produced: that is how "the cell ran"
+    # becomes something the user can see (FR-UX-4), and it writes nothing new.
+    "verify": frozenset({SafetyClass.READ, SafetyClass.EXEC, SafetyClass.UI}),
+    "report": frozenset({SafetyClass.READ, SafetyClass.UI}),
+}
+
+
+class Phase:
+    SURVEY = "survey"
+    PLAN = "plan"
+    ACT = "act"
+    VERIFY = "verify"
+    REPORT = "report"
+
+    ALL = (SURVEY, PLAN, ACT, VERIFY, REPORT)
+
+
+def build_policy(
+    repo_root: Path,
+    cfg: Config,
+    *,
+    interactive: bool = True,
+    scratch: Path | None = None,
+) -> Policy:
+    return Policy(
+        repo_root=Path(repo_root),
+        interactive=interactive,
+        allow_read=[Path(p) for p in cfg.tools.allow_read],
+        push_ref_prefix=cfg.git.push_ref_prefix,
+        allowed_remotes=tuple(cfg.git.remotes),
+        require_approval=tuple(cfg.safety.require_approval),
+        deny_rules=tuple(cfg.safety.deny) if cfg.safety.deny else DEFAULT_DENIED,
+        scratch=scratch if scratch is not None else Path(repo_root) / ".coagent" / "tmp",
+    )
+
+
+def build_exec_config(repo_root: Path, cfg: Config) -> ExecConfig:
+    return ExecConfig(
+        repo_root=Path(repo_root),
+        max_output_bytes=cfg.tools.max_output_bytes,
+        timeout_s=cfg.tools.shell_timeout_s,
+        notebook_timeout_s=cfg.tools.notebook_timeout_s,
+        hide_gpu=True,  # PRD D4: verification is CPU-only by default
+        engine_dir=Path(repo_root) / ".coagent" / "tmp",
+    )
+
+
+def build_registry(
+    repo_root: Path,
+    cfg: Config,
+    *,
+    phase: str = Phase.ACT,
+    policy: Policy | None = None,
+    session: FileSession | None = None,
+) -> ToolRegistry:
+    """Every tool this phase may use, already filtered by safety class.
+
+    ``session`` is shared across phases when the caller has one, because
+    read-before-write and the artifact store are per-*session* state, not
+    per-phase: SURVEY reading a file must satisfy ACT's edit guard.
+    """
+    root = Path(repo_root)
+    policy = policy or (session.policy if session is not None else build_policy(root, cfg))
+    if session is None:
+        session = FileSession(repo_root=root, policy=policy)
+    exec_cfg = build_exec_config(root, cfg)
+    session.exec_cfg = exec_cfg
+    if session.artifact_store is None:
+        session.artifact_store = ArtifactStore(
+            root,
+            getattr(session, "run_id", "") or "run",
+            commit_under_mb=cfg.artifacts.commit_under_mb,
+            drive_dir=cfg.artifacts.drive_dir,
+        )
+
+    all_tools: list[BaseTool] = [
+        ListDirTool(session),
+        ReadFileTool(session),
+        GrepTool(session),
+        EditFileTool(session),
+        WriteFileTool(session),
+        # Notebooks are first-class (PRD D-2): a plot-and-cell task is a task,
+        # not a source-file task with a JSON side quest.
+        ReadNotebookTool(session),
+        EditNotebookTool(session),
+        ExecNotebookTool(session),
+        SaveArtifactTool(session),
+        DisplayArtifactTool(session),
+        RunShellTool(exec_cfg, policy),
+        RunTestsTool(
+            exec_cfg,
+            policy,
+            verify_commands=list(cfg.verify.commands),
+            feedback_max_tokens=cfg.verify.feedback_max_tokens,
+        ),
+        RunPythonTool(exec_cfg, policy),
+    ]
+    allowed = PHASE_SAFETY.get(phase)
+    if allowed is None:
+        raise ValueError(f"unknown phase {phase!r}; expected one of {list(PHASE_SAFETY)}")
+    return ToolRegistry([t for t in all_tools if t.safety in allowed])