director-cli 0.3.0__py3-none-any.whl

director/gitutil.py

@@ -0,0 +1,83 @@
+"""Thin git helpers. Director uses real git branches + worktrees for isolation."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+
+def git(args: list[str], cwd: str | Path, check: bool = True) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["git", *args],
+        cwd=str(cwd),
+        capture_output=True,
+        text=True,
+        check=check,
+    )
+
+
+def current_commit(cwd: str | Path) -> str:
+    return git(["rev-parse", "HEAD"], cwd).stdout.strip()
+
+
+def current_branch(cwd: str | Path) -> str:
+    return git(["rev-parse", "--abbrev-ref", "HEAD"], cwd).stdout.strip()
+
+
+def branch_exists(name: str, cwd: str | Path) -> bool:
+    return git(["rev-parse", "--verify", "--quiet", name], cwd, check=False).returncode == 0
+
+
+def create_branch(name: str, cwd: str | Path, base: str | None = None) -> None:
+    args = ["branch", name] + ([base] if base else [])
+    git(args, cwd)
+
+
+def checkout(name: str, cwd: str | Path) -> None:
+    git(["checkout", name], cwd)
+
+
+def worktree_add(path: str | Path, branch: str, base: str, cwd: str | Path) -> None:
+    """Create a new branch `branch` from `base` checked out at `path`."""
+    git(["worktree", "add", "-b", branch, str(path), base], cwd)
+
+
+def worktree_remove(path: str | Path, cwd: str | Path) -> None:
+    git(["worktree", "remove", "--force", str(path)], cwd, check=False)
+
+
+def changed_paths(cwd: str | Path) -> list[str]:
+    """All paths modified/added/deleted vs HEAD, including untracked (ignored
+    files excluded). Used to enforce the file allowlist."""
+    out = git(["status", "--porcelain", "--untracked-files=all"], cwd).stdout
+    paths: list[str] = []
+    for line in out.splitlines():
+        if not line.strip():
+            continue
+        # format: "XY <path>" or rename "XY old -> new"
+        p = line[3:]
+        if " -> " in p:
+            p = p.split(" -> ", 1)[1]
+        paths.append(p.strip().strip('"'))
+    return paths
+
+
+def commit_all(message: str, cwd: str | Path) -> bool:
+    """Stage everything and commit. Returns False if there was nothing to commit.
+    Signing is disabled so headless runs never block on a passphrase."""
+    git(["add", "-A"], cwd)
+    if not git(["status", "--porcelain"], cwd).stdout.strip():
+        return False
+    git(["-c", "commit.gpgsign=false", "commit", "-q", "-m", message], cwd)
+    return True
+
+
+def merge_branch(
+    branch: str, cwd: str | Path, message: str | None = None
+) -> subprocess.CompletedProcess:
+    """Merge `branch` into the current branch (no fast-forward, unsigned)."""
+    args = ["-c", "commit.gpgsign=false", "merge", "--no-ff"]
+    if message:
+        args += ["-m", message]
+    args.append(branch)
+    return git(args, cwd, check=False)

director/metrics.py

@@ -0,0 +1,48 @@
+"""Metrics stream (Phase 3) — `.director/metrics.jsonl`.
+
+The hypothesis is falsifiable, so every run must be measurable. This is an
+append-only NDJSON stream: one `kind:"node"` record per finished node and one
+`kind:"run"` summary record at the end. It is written alongside the cost ledger
+(`costs.jsonl`) and run state (`state.json`), and is what `director bench` and any
+external analysis read to compare profiles.
+
+Keeping metrics in their own stream (rather than overloading the cost ledger)
+means the cost story stays a pure per-call ledger while metrics carry the derived
+rates (escalation, stage-two trigger, watch-it-fail) and wall time.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+
+class MetricsWriter:
+    """Append-only metrics stream backed by .director/metrics.jsonl."""
+
+    def __init__(self, path: Path):
+        self.path = Path(path)
+
+    def write(self, record: dict) -> None:
+        rec = {"ts": time.time(), **record}
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self.path.open("a") as f:
+            f.write(json.dumps(rec) + "\n")
+
+
+def read_records(path: Path) -> list[dict]:
+    """Load all metrics records (both kinds) from a metrics.jsonl, oldest first."""
+    path = Path(path)
+    out: list[dict] = []
+    if path.exists():
+        for line in path.read_text().splitlines():
+            if line.strip():
+                out.append(json.loads(line))
+    return out
+
+
+def latest_run(path: Path) -> dict | None:
+    """The most recent run-level summary record, if any."""
+    runs = [r for r in read_records(path) if r.get("kind") == "run"]
+    return runs[-1] if runs else None

director/models.py

@@ -0,0 +1,106 @@
+"""Core data structures: the task DAG (Plan/Node) and per-node run State."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+
+
+@dataclass
+class Node:
+    """One atomic unit of work. `spec` must be self-contained — readable by the
+    executor with zero other context."""
+
+    id: str
+    title: str
+    spec: str
+    files: list[str]  # allowlist: the ONLY files the executor may modify
+    depends_on: list[str] = field(default_factory=list)
+    test_cmd: str = ""  # command that gates this node (nonzero = fail)
+    tests: list[str] = field(default_factory=list)  # test file paths (test-author writes these)
+    estimated_difficulty: str = "medium"  # easy | medium | hard
+    # sha256 of each test file, captured by director once tests are authored (NOT
+    # emitted by the planner). The node gate refuses to pass if a test file's hash
+    # changed — the executor may not edit the contract. See gates.test_files_intact.
+    test_hashes: dict = field(default_factory=dict)  # {test_path: sha256}
+
+    @staticmethod
+    def from_dict(d: dict) -> Node:
+        # Tolerate common field-name drift from different planner models.
+        spec = d.get("spec") or d.get("description") or d.get("desc")
+        files = d.get("files") or d.get("files_to_modify") or d.get("file_allowlist") or []
+        tests = d.get("tests") or d.get("test_files")
+        if tests is None:
+            tf = d.get("test_file") or d.get("test")
+            tests = [tf] if isinstance(tf, str) else (tf or [])
+        if spec is None:
+            raise KeyError(f"node {d.get('id')!r} has no spec/description")
+        return Node(
+            id=str(d["id"]),
+            title=d.get("title", str(d["id"])),
+            spec=spec,
+            files=list(files),
+            depends_on=[str(x) for x in d.get("depends_on", [])],
+            test_cmd=d.get("test_cmd", ""),
+            tests=list(tests),
+            estimated_difficulty=d.get("estimated_difficulty", "medium"),
+            test_hashes=dict(d.get("test_hashes", {})),
+        )
+
+
+@dataclass
+class Plan:
+    job_id: str
+    task: str
+    repo: str
+    created_at: str
+    job_branch: str
+    nodes: list[Node] = field(default_factory=list)
+
+    def node(self, node_id: str) -> Node:
+        for n in self.nodes:
+            if n.id == node_id:
+                return n
+        raise KeyError(node_id)
+
+    def to_json(self) -> str:
+        d = asdict(self)
+        return json.dumps(d, indent=2)
+
+    @staticmethod
+    def from_json(text: str) -> Plan:
+        d = json.loads(text)
+        return Plan(
+            job_id=d["job_id"],
+            task=d["task"],
+            repo=d["repo"],
+            created_at=d["created_at"],
+            job_branch=d["job_branch"],
+            nodes=[Node.from_dict(n) for n in d["nodes"]],
+        )
+
+
+# Node lifecycle statuses persisted in .director/state.json (resumable).
+PENDING, RUNNING, DONE, ESCALATED, FAILED = "pending", "running", "done", "escalated", "failed"
+
+
+@dataclass
+class NodeState:
+    id: str
+    status: str = PENDING
+    attempts: int = 0  # executor-tier attempts used
+    tier_used: str | None = None  # "executor" | "escalation"
+    model_used: str | None = None
+    escalated: bool = False
+    tokens: dict = field(default_factory=lambda: {"input": 0, "output": 0})
+    cost_usd: float = 0.0
+    error: str | None = None
+    worktree: str | None = None
+    # Phase 2.5 two-stage review
+    review_stage_two: bool = False  # did the conditional code-quality review run?
+    review_blocks: int = 0  # # of attempts re-opened by a critical finding
+    review_summary: str | None = None  # reviewer's last one-line verdict summary
+    # Phase 3 measurement
+    wall_secs: float = 0.0  # wall time for the node
+    watch_it_fail: str | None = None  # "observed" | "not_observed" | "unknown"
+    flake_failed: bool = False  # a flake re-run failed this node on some attempt

director/opencode.py

@@ -0,0 +1,231 @@
+"""Headless OpenCode driver.
+
+Wraps `opencode run --agent <role> --model <provider/model> --format json` and
+parses the NDJSON event stream into a structured result (assistant text + token
+usage + tool activity). This is the ONLY place that shells out to OpenCode.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# Director-spawned processes (and the test commands they run) must not litter the
+# worktree with Python bytecode: a stray `__pycache__/*.pyc` would otherwise get
+# `git add -A`-ed into a node commit, poison later merges, and inflate the
+# changed-file count. Suppressing it at the source keeps every worktree clean.
+_CLEAN_ENV = {**os.environ, "PYTHONDONTWRITEBYTECODE": "1"}
+
+
+@dataclass
+class RunResult:
+    returncode: int
+    text: str  # concatenated assistant text (e.g. planner JSON)
+    tokens: dict  # summed across steps: {input, output, reasoning, total}
+    cost_reported: float  # OpenCode's own cost sum (cross-check; often 0 locally)
+    n_steps: int
+    tool_calls: list[tuple[str, str]] = field(default_factory=list)  # (tool, status)
+    tool_events: list[dict] = field(default_factory=list)  # ordered {name,status,blob}
+    error: str | None = None
+    timed_out: bool = False
+    log_path: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.returncode == 0 and self.error is None and not self.timed_out
+
+
+def run_agent(
+    *,
+    agent: str,
+    model: str,
+    message: str,
+    cwd: str | Path,
+    log_path: str | Path,
+    timeout: int,
+) -> RunResult:
+    """Invoke an OpenCode agent headlessly in `cwd`. NDJSON events go to
+    `log_path`; OpenCode logs go to `log_path + '.stderr'`. Never raises on a
+    model/agent failure — inspect RunResult.ok / .error / .timed_out."""
+    log_path = Path(log_path)
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    err_path = log_path.with_suffix(log_path.suffix + ".stderr")
+
+    # --dir pins the project/worktree explicitly. Without it, `opencode run`
+    # resolves the project root by walking up for a .git and can land on an
+    # ENCLOSING repo (so edits leak out of an isolated worktree). Worktrees are
+    # also placed outside the repo tree (see run.py) to make this airtight.
+    cmd = [
+        "opencode",
+        "run",
+        "--dir",
+        str(cwd),
+        "--agent",
+        agent,
+        "--model",
+        model,
+        "--format",
+        "json",
+        "--print-logs",
+        message,
+    ]
+
+    timed_out = False
+    with open(log_path, "wb") as out, open(err_path, "wb") as err:
+        proc = subprocess.Popen(cmd, cwd=str(cwd), stdout=out, stderr=err, env=_CLEAN_ENV)
+        try:
+            rc = proc.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait()
+            rc = 124
+            timed_out = True
+
+    return _parse(log_path, rc, timed_out)
+
+
+def _parse(log_path: Path, rc: int, timed_out: bool) -> RunResult:
+    text_parts: list[str] = []
+    tokens = {"input": 0, "output": 0, "reasoning": 0, "total": 0}
+    cost_reported = 0.0
+    n_steps = 0
+    tool_calls: list[tuple[str, str]] = []
+    tool_events: list[dict] = []
+    error: str | None = None
+
+    for line in log_path.read_text(errors="replace").splitlines():
+        line = line.strip()
+        if not line.startswith("{"):
+            continue
+        try:
+            evt = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        etype = evt.get("type")
+        part = evt.get("part", {}) if isinstance(evt.get("part"), dict) else {}
+
+        if etype == "text":
+            text_parts.append(part.get("text", ""))
+        elif etype in ("step_finish", "step-finish"):
+            n_steps += 1
+            tk = part.get("tokens", {}) or {}
+            for k in ("input", "output", "reasoning", "total"):
+                tokens[k] += int(tk.get(k, 0) or 0)
+            cost_reported += float(part.get("cost", 0) or 0)
+        elif etype in ("tool", "tool_use"):
+            name = part.get("tool", "?")
+            status = (part.get("state", {}) or {}).get("status", "?")
+            tool_calls.append((name, status))
+            # keep an ordered, capped content blob per tool event so the
+            # watch-it-fail analyzer can tell a test run from a file edit and spot
+            # a failure in the command output (shape-tolerant: just stringify part).
+            blob = json.dumps(part, default=str)[:2000].lower()
+            tool_events.append({"name": str(name).lower(), "status": str(status), "blob": blob})
+        elif etype in ("error", "invalid_request_error") or "error" in (etype or ""):
+            # error events may be at top level (evt["error"]) or in part
+            msg = evt.get("error") or part.get("error") or part.get("message") or etype
+            error = str(msg)
+
+    if tokens["total"] == 0:
+        tokens["total"] = tokens["input"] + tokens["output"]
+
+    return RunResult(
+        returncode=rc,
+        text="".join(text_parts).strip(),
+        tokens=tokens,
+        cost_reported=cost_reported,
+        n_steps=n_steps,
+        tool_calls=tool_calls,
+        tool_events=tool_events,
+        error=error,
+        timed_out=timed_out,
+        log_path=str(log_path),
+    )
+
+
+# --------------------------------------------------------------------------- #
+# watch-it-fail transcript verification (Phase 3)
+# --------------------------------------------------------------------------- #
+# Tool-name fragments. OpenCode names vary by provider/model, so match on
+# substrings rather than exact names.
+_EDIT_TOOLS = ("edit", "write", "patch", "create", "apply", "str_replace")
+_SHELL_TOOLS = ("bash", "shell", "run", "execute", "terminal", "command")
+_TEST_SIGNALS = ("pytest", "unittest", "test", "vitest", "jest", "go test", "cargo test")
+_FAIL_SIGNALS = (
+    "failed",
+    "error",
+    "traceback",
+    "assertion",
+    "exit code 1",
+    "non-zero",
+    "fail (",
+    " failures=",
+    "no tests ran",
+)
+
+
+@dataclass
+class WatchItFail:
+    verdict: str  # "observed" | "not_observed" | "unknown"
+    ran_before_edit: bool
+    observed_failure: bool
+    detail: str
+
+    @property
+    def observed(self) -> bool:
+        return self.verdict == "observed"
+
+
+def _is_edit(name: str) -> bool:
+    return any(t in name for t in _EDIT_TOOLS)
+
+
+def _is_shell(name: str) -> bool:
+    return any(t in name for t in _SHELL_TOOLS)
+
+
+def _looks_like_test(blob: str, test_cmd: str) -> bool:
+    if any(s in blob for s in _TEST_SIGNALS):
+        return True
+    # also match a distinctive token from the configured test command
+    _skip = ("python", "python3", "-m", "discover", "&&")
+    for tok in test_cmd.lower().replace("/", " ").replace(".", " ").split():
+        if len(tok) > 3 and tok not in _skip and tok in blob:
+            return True
+    return False
+
+
+def watch_it_fail(events: list[dict], test_cmd: str) -> WatchItFail:
+    """Did the executor run the (failing) tests BEFORE its first edit? (Phase 3 §1)
+
+    Advisory — the deterministic node gate already enforces tests-pass and
+    contract-intact; this verifies the *discipline* (red before green) from the
+    transcript, surfaced as a metric. Returns "unknown" when the transcript
+    carries no usable tool activity (can't be held against the node)."""
+    if not events:
+        return WatchItFail("unknown", False, False, "no tool activity in transcript")
+
+    saw_test = False
+    saw_failure = False
+    for ev in events:
+        name, blob = ev.get("name", ""), ev.get("blob", "")
+        if _is_shell(name) and _looks_like_test(blob, test_cmd):
+            saw_test = True
+            if any(s in blob for s in _FAIL_SIGNALS):
+                saw_failure = True
+            return WatchItFail(
+                "observed",
+                True,
+                saw_failure,
+                "ran tests before first edit" + (" (saw failure)" if saw_failure else ""),
+            )
+        if _is_edit(name):
+            # an edit happened before any test run → watch-it-fail not honored
+            return WatchItFail("not_observed", False, False, "edited before running any tests")
+    # tools ran but none matched a test command or an edit
+    return WatchItFail(
+        "unknown", saw_test, saw_failure, "no test run or edit detected among tool calls"
+    )