cih-agent 0.1.0__py3-none-any.whl

cih/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

cih/agents.py

@@ -0,0 +1,57 @@
+# cih/agents.py
+import json
+import subprocess
+from typing import Protocol
+from cih.contracts import AgentContract
+
+class AgentRunner(Protocol):
+    def run(self, contract: AgentContract, input_data: dict) -> dict: ...
+
+class StubRunner:
+    """Test double: returns canned responses keyed by role."""
+    def __init__(self, responses: dict):
+        self.responses = responses
+        self.calls: list[dict] = []
+
+    def run(self, contract: AgentContract, input_data: dict) -> dict:
+        self.calls.append({"role": contract.role, "input": input_data})
+        if contract.role not in self.responses:
+            raise KeyError(f"no stub response for role {contract.role}")
+        return self.responses[contract.role]
+
+class ClaudeCliRunner:
+    """Headless adapter: drives `claude -p --append-system-prompt`.
+
+    Flags precede the prompt; output is expected as JSON on stdout.
+    """
+    def __init__(self, cwd: str, extra_args: list[str] | None = None):
+        self.cwd = cwd
+        self.extra_args = extra_args or []
+
+    def run(self, contract: AgentContract, input_data: dict) -> dict:
+        prompt = json.dumps(input_data)
+        cmd = ["claude", "-p", "--output-format", "json",
+               "--append-system-prompt", contract.role_prompt,
+               *self.extra_args, "--", prompt]
+        proc = subprocess.run(cmd, cwd=self.cwd, capture_output=True, text=True)
+        if proc.returncode != 0:
+            raise RuntimeError(f"claude failed for {contract.role}: {proc.stderr}")
+        try:
+            envelope = json.loads(proc.stdout)
+        except json.JSONDecodeError as e:
+            raise RuntimeError(f"{contract.role}: non-JSON stdout from claude -p: {proc.stdout[:500]!r}") from e
+        if envelope.get("is_error"):
+            raise RuntimeError(f"{contract.role}: claude reported error: {envelope.get('result')}")
+        result = envelope.get("result")
+        if isinstance(result, dict):
+            return result
+        try:
+            return json.loads(result)
+        except (TypeError, json.JSONDecodeError) as e:
+            from cih.contracts import OutputValidationError
+            raise OutputValidationError(f"{contract.role}: result was not JSON: {result!r}") from e
+
+def invoke(runner: AgentRunner, contract: AgentContract, input_data: dict) -> dict:
+    output = runner.run(contract, input_data)
+    contract.validate_output(output)
+    return output

cih/attempts.py

@@ -0,0 +1,61 @@
+from dataclasses import dataclass, asdict
+from enum import Enum
+from typing import Optional
+
+class AttemptKind(str, Enum):
+    PLAN = "plan_retry"
+    EXECUTION = "execution_retry"
+    INTEGRATION = "integration_retry"
+    FINAL_REJECT = "final_reject"
+
+class AttemptCapExceeded(Exception):
+    pass
+
+@dataclass
+class Attempt:
+    attempt_id: str
+    kind: str
+    base_sha: str
+    branch: str
+    worktree_path: str
+    feedback_input: str
+    parent_attempt_id: Optional[str] = None
+    is_current: bool = True
+
+class AttemptLog:
+    def __init__(self, team_id: str, cap: int):
+        self.team_id = team_id
+        self.cap = cap
+        self._attempts: list[Attempt] = []
+
+    def start(self, kind: AttemptKind, base_sha: str, branch: str,
+              worktree_path: str, feedback: str,
+              parent: Optional[str] = None) -> Attempt:
+        if len(self._attempts) >= self.cap:
+            raise AttemptCapExceeded(
+                f"{self.team_id}: attempt cap {self.cap} reached")
+        for a in self._attempts:
+            a.is_current = False
+        att = Attempt(
+            attempt_id=f"attempt-{len(self._attempts)+1:02d}",
+            kind=kind.value if isinstance(kind, AttemptKind) else kind,
+            base_sha=base_sha, branch=branch, worktree_path=worktree_path,
+            feedback_input=feedback, parent_attempt_id=parent)
+        self._attempts.append(att)
+        return att
+
+    def current(self) -> Optional[Attempt]:
+        return self._attempts[-1] if self._attempts else None
+
+    def all(self) -> list[Attempt]:
+        return list(self._attempts)
+
+    def to_dict(self) -> dict:
+        return {"team_id": self.team_id, "cap": self.cap,
+                "attempts": [asdict(a) for a in self._attempts]}
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "AttemptLog":
+        log = cls(team_id=d["team_id"], cap=d["cap"])
+        log._attempts = [Attempt(**a) for a in d["attempts"]]
+        return log

cih/config.py

@@ -0,0 +1,81 @@
+import os
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+from typing import Optional
+
+class ConfigError(Exception):
+    pass
+
+_MODES = {"fixed-N", "until-converged"}
+
+DEPTH_BUDGET = {"low": 3, "medium": 6, "high": 10}
+DEFAULT_DEPTH = "medium"
+
+
+def depth_budget(name: Optional[str] = None) -> int:
+    """Map a --depth name to its question budget (upper bound). None → default."""
+    if name is None:
+        name = DEFAULT_DEPTH
+    if name not in DEPTH_BUDGET:
+        raise ConfigError(
+            f"depth must be one of {sorted(DEPTH_BUDGET, key=DEPTH_BUDGET.__getitem__)} (got {name!r})"
+        )
+    return DEPTH_BUDGET[name]
+
+
+@dataclass
+class RunConfig:
+    mode: str
+    target_repo: str
+    state_dir: str
+    iterations: Optional[int] = None
+    max_iterations: int = 25
+    budget_cap: Optional[int] = None
+    focus_areas: list[str] = field(default_factory=list)
+    value_threshold: float = 0.5
+    convergence_dry_streak: int = 2
+    plan_review_retries: int = 2
+    exec_review_retries: int = 2
+    max_teams_per_iteration: int = 4
+    integration_retries: int = 2
+    per_team_attempt_cap: int = 4
+    cooldown_iterations: int = 2
+    opportunity_max_attempts: int = 3
+    tdd_adapter: str = "pytest"
+
+    @staticmethod
+    def _validate_paths(target_repo: str, state_dir: str) -> None:
+        for label, p in (("target_repo", target_repo), ("state_dir", state_dir)):
+            if not os.path.isabs(p):
+                raise ConfigError(f"{label} must be an absolute path: {p}")
+        t = Path(target_repo).resolve()
+        s = Path(state_dir).resolve()
+        if t == s:
+            raise ConfigError("target_repo and state_dir must be distinct")
+        if t in s.parents or s in t.parents:
+            raise ConfigError("state_dir must not be nested inside target_repo (or vice versa)")
+        for label, p in (("target_repo", t), ("state_dir", s)):
+            if not p.is_dir():
+                raise ConfigError(f"{label} must be an existing directory: {p}")
+
+    @classmethod
+    def create(cls, **kwargs) -> "RunConfig":
+        mode = kwargs.get("mode")
+        if mode not in _MODES:
+            raise ConfigError(f"mode must be one of {_MODES}")
+        iterations = kwargs.get("iterations")
+        if mode == "fixed-N":
+            if not isinstance(iterations, int) or iterations <= 0:
+                raise ConfigError("fixed-N mode requires iterations to be a positive int")
+        elif mode == "until-converged":
+            if iterations is not None:
+                raise ConfigError("until-converged mode must not set iterations")
+        cls._validate_paths(kwargs["target_repo"], kwargs["state_dir"])
+        return cls(**kwargs)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "RunConfig":
+        return cls.create(**d)

cih/contracts.py

@@ -0,0 +1,32 @@
+# cih/contracts.py
+import hashlib
+import json
+from dataclasses import dataclass, field
+from jsonschema import validate, ValidationError
+
+class OutputValidationError(Exception):
+    pass
+
+@dataclass
+class AgentContract:
+    role: str
+    agent_version: str
+    role_prompt: str
+    input_schema: dict
+    output_schema: dict
+    allowed_tools: list = field(default_factory=list)
+    runtime_adapter_settings: dict = field(default_factory=dict)
+
+    def validate_output(self, output: dict) -> None:
+        try:
+            validate(instance=output, schema=self.output_schema)
+        except ValidationError as e:
+            raise OutputValidationError(f"{self.role} output invalid: {e.message}") from e
+
+    def prompt_hash(self) -> str:
+        blob = json.dumps({"prompt": self.role_prompt, "in": self.input_schema,
+                           "out": self.output_schema, "v": self.agent_version,
+                           "tools": self.allowed_tools,
+                           "adapter": self.runtime_adapter_settings},
+                          sort_keys=True)
+        return hashlib.sha256(blob.encode()).hexdigest()[:16]

cih/integration.py

@@ -0,0 +1,192 @@
+# cih/integration.py
+"""Real git-backed integration layer for the orchestrator.
+
+`build_integration` wires up a `(team_runner, integrate_fn)` pair that share an
+internal `WorktreeManager`, a mutable integration `head`, and a per-iteration
+`pending` registry. team_runner runs each team in its own iteration-scoped
+worktree (branched off the CURRENT integration head), keeping it for passed
+teams and removing it for failed/crashed ones, and persists per-team artifacts.
+
+integrate_fn MERGES each passing team's branch into a single, advancing
+integration worktree/branch (`cih/<run_id>/integration`), re-runs the suite +
+execution-reviewer there, and threads the rolling tip via the merge queue.
+Using merge (not rebase) preserves the executor commit SHAs so `reconcile` can
+still resolve them, and lets iteration N+1 build on iteration N's merged result.
+"""
+import functools
+import subprocess
+from pathlib import Path
+
+from cih import merge_queue
+from cih.agents import invoke
+from cih.safety import GitError, run_git
+from cih.state import StateHeader, write_state
+from cih.tdd_verifier import verify_tdd
+from cih.team import TeamResult, run_team
+from cih.worktree import WorktreeManager
+
+
+def build_integration(*, contracts, runner, verifier=None, repo, worktrees_root, run_id,
+                      base_sha, state_dir, plan_review_retries, exec_review_retries,
+                      attempt_cap, integration_retries, tdd_adapter="pytest", log=None):
+    mgr = WorktreeManager(repo, worktrees_root, run_id, log)
+    repo = Path(repo)
+    worktrees_root = Path(worktrees_root)
+    state_dir = Path(state_dir)
+    pending: dict[str, dict] = {}
+    # Run-scoped (NOT cleared per iteration): every passed-team worktree we keep.
+    # teardown() removes these dirs at run end while preserving their branches.
+    kept: list = []
+
+    # Mutable integration state, advances across iterations so improvements compound.
+    int_branch = f"cih/{run_id}/integration"
+    state = {"head": base_sha, "int_wt": None}
+
+    def _ensure_int_wt():
+        if state["int_wt"] is None:
+            int_wt = worktrees_root / run_id / "integration"
+            int_wt.parent.mkdir(parents=True, exist_ok=True)
+            run_git(["worktree", "add", "-b", int_branch, str(int_wt), state["head"]],
+                    cwd=repo, log=log)
+            state["int_wt"] = int_wt
+        return state["int_wt"]
+
+    def _persist(iteration, team_id, result, wt=None):
+        iter_id = f"iter-{iteration:03d}"
+        teamdir = state_dir / "iterations" / iter_id / "teams" / team_id
+        status = "passed" if result.passed else "failed"
+        header = StateHeader(run_id, iter_id, team_id, None, status, "team")
+
+        body = {"commits": result.commits}
+        if wt is not None:
+            body["branch"] = wt.branch
+            try:
+                body["head_sha"] = mgr.head_sha(wt)
+            except GitError:
+                body["head_sha"] = None
+        write_state(teamdir / "plan.json", header, result.plan)
+        write_state(teamdir / "execution.json", header, body)
+        write_state(teamdir / "exec_review.json", header,
+                    {"passed": result.passed, "reason": result.reason})
+        write_state(teamdir / "attempts.json", header, {"attempts": result.attempts})
+
+    def team_runner(charters, ctx):
+        iteration = ctx["iteration"]
+        iter_id = f"iter-{iteration:03d}"
+        # Reset pending so integrate_fn only ever processes THIS iteration's teams.
+        pending.clear()
+        results = []
+        for charter in charters:
+            team_id = charter["id"]
+            # Iteration-scoped worktree/branch: cih/<run_id>/iter-NNN/<team_id>.
+            # Branch off the CURRENT integration head so teams build on prior merges.
+            wt = mgr.create(f"{iter_id}/{team_id}", state["head"])
+            # When no explicit verifier is injected (production), bind a real
+            # mechanical TDD verifier to THIS team's worktree path.
+            team_verifier = verifier
+            if team_verifier is None:
+                team_verifier = functools.partial(
+                    verify_tdd, repo=wt.path, adapter=tdd_adapter)
+            try:
+                result = run_team(
+                    charter=charter, contracts=contracts, runner=runner,
+                    verifier=team_verifier, plan_review_retries=plan_review_retries,
+                    exec_review_retries=exec_review_retries, attempt_cap=attempt_cap,
+                    base_sha=state["head"], branch=wt.branch, worktree_path=wt.path)
+            except Exception as e:  # don't leak the worktree on an unexpected crash
+                mgr.remove(wt)
+                result = TeamResult(team_id, False, f"team crashed: {e}")
+                _persist(iteration, team_id, result)
+                results.append(result)
+                continue
+            _persist(iteration, team_id, result, wt=wt)
+            if result.passed:
+                pending[team_id] = {"worktree": wt, "charter": charter,
+                                    "result": result}
+                kept.append(wt)
+            else:
+                mgr.remove(wt)
+            results.append(result)
+        return results
+
+    def integrate_fn(results, ctx):
+        teams = [(tid, pending[tid]["charter"]) for tid in pending
+                 if pending[tid]["result"].passed]
+        if not teams:
+            return merge_queue.MergeOutcome(final_base_sha=state["head"])
+
+        int_wt = _ensure_int_wt()
+        base = state["head"]
+
+        def reverify(team_id, current_base):
+            # Operate on the single advancing integration worktree. We merge into
+            # the integration branch (which already advanced past prior merges);
+            # current_base is bookkeeping only — the actual merge target is the
+            # integration HEAD. On any rejection we reset back to `base`.
+            team_branch = pending[team_id]["worktree"].branch
+            try:
+                run_git(["merge", "--no-ff", "--no-edit", team_branch],
+                        cwd=int_wt, log=log)
+            except GitError:  # merge conflict
+                try:
+                    run_git(["merge", "--abort"], cwd=int_wt, log=log)
+                except GitError:
+                    pass
+                return (False, None)
+
+            def _reject():
+                run_git(["reset", "--hard", base], cwd=int_wt, log=log)
+                return (False, None)
+
+            # Full suite in the integration worktree (exit 5 == no tests, ok).
+            proc = subprocess.run(["python", "-m", "pytest", "-q"],
+                                  cwd=int_wt, capture_output=True, text=True)
+            if proc.returncode not in (0, 5):
+                return _reject()
+            review = invoke(runner, contracts["execution-reviewer"],
+                            {"team_id": team_id, "merged": True})
+            if not review["approved"]:
+                return _reject()
+            return (True, run_git(["rev-parse", "HEAD"], cwd=int_wt, log=log).strip())
+
+        # integration_retries=0: an in-call retry of a deterministic merge is a
+        # no-op. Cross-iteration recovery happens via the orchestrator ledger
+        # cooldown -> reopen, which re-runs a FRESH executor against the new base
+        # next iteration — that IS "re-execute against a new base" at iteration
+        # granularity.
+        outcome = merge_queue.integrate(
+            teams, base_sha=base, reverify=reverify, integration_retries=0)
+
+        if outcome.merged:
+            state["head"] = outcome.final_base_sha
+            # Belt-and-suspenders: the integration worktree branch already points
+            # here; keep the stable ref in sync for reconcile/resume.
+            run_git(["update-ref", f"refs/heads/{int_branch}", state["head"]],
+                    cwd=repo, log=log)
+        return outcome
+
+    def teardown():
+        # Best-effort: prune the worktree DIRECTORIES (integration + every kept
+        # team worktree) at run end while PRESERVING all branch refs, so
+        # reconcile/resume still find them. Idempotent — git's `worktree remove`
+        # on an already-removed worktree raises GitError, which we swallow.
+        int_wt = state.get("int_wt")
+        if int_wt is not None:
+            try:
+                run_git(["worktree", "remove", "--force", str(int_wt)],
+                        cwd=repo, log=log)
+            except GitError:
+                pass
+        for wt in kept:
+            try:
+                run_git(["worktree", "remove", "--force", wt.path],
+                        cwd=repo, log=log)
+            except GitError:
+                pass
+        try:
+            run_git(["worktree", "prune"], cwd=repo, log=log)
+        except GitError:
+            pass
+
+    integrate_fn.teardown = teardown
+    return team_runner, integrate_fn

cih/ledger.py

@@ -0,0 +1,102 @@
+# cih/ledger.py
+import hashlib
+import re
+from dataclasses import dataclass, field, asdict
+from typing import Optional
+
+from cih.transitions import Status, assert_transition
+
+def fingerprint(title: str, scope: str) -> str:
+    norm = re.sub(r"\s+", " ", title.strip().lower())
+    return hashlib.sha256(f"{norm}|{scope}".encode()).hexdigest()[:16]
+
+@dataclass
+class Opportunity:
+    fp: str
+    title: str
+    scope: str
+    value: float
+    confidence: float
+    effort: float
+    risk: float
+    rationale: str
+    state: str = "open"
+    attempt_count: int = 0
+    cooldown_until: Optional[int] = None
+
+class Ledger:
+    def __init__(self):
+        self._items: dict[str, Opportunity] = {}
+
+    def upsert(self, opp: Opportunity) -> None:
+        existing = self._items.get(opp.fp)
+        if existing and existing.state in ("merged", "expired"):
+            return  # terminal; ignore re-discovery
+        if existing:
+            opp.attempt_count = existing.attempt_count
+            opp.state = existing.state
+            opp.cooldown_until = existing.cooldown_until
+        self._items[opp.fp] = opp
+
+    def get(self, fp: str) -> Optional[Opportunity]:
+        return self._items.get(fp)
+
+    def _set_state(self, o, dst: str) -> None:
+        # A same-state write is an idempotent no-op (e.g. a still-cooling item
+        # re-entering cooldown on a subsequent failed retry); it is trivially
+        # monotonic, so it does not need a table edge.
+        if o.state == dst:
+            return
+        assert_transition(Status(o.state), Status(dst))
+        o.state = dst
+
+    def _refresh_cooldowns(self, current_iteration: Optional[int]) -> None:
+        if current_iteration is None:
+            return
+        for o in self._items.values():
+            if o.state == "cooldown" and o.cooldown_until is not None \
+                    and current_iteration >= o.cooldown_until:
+                self._set_state(o, "open")
+                o.cooldown_until = None
+
+    def select_open(self, value_threshold: float,
+                    current_iteration: Optional[int] = None) -> list[Opportunity]:
+        self._refresh_cooldowns(current_iteration)
+        return [o for o in self._items.values()
+                if o.state == "open" and o.value >= value_threshold]
+
+    def is_dry(self, value_threshold: float, current_iteration: int) -> bool:
+        # Spec §5: dry = no open opportunity above threshold AND no retryable
+        # opportunity OUTSIDE cooldown. select_open() refreshes cooldowns first,
+        # so items whose cooldown has elapsed are already reopened and counted;
+        # items still cooling are correctly excluded.
+        return not self.select_open(value_threshold, current_iteration)
+
+    def mark_merged(self, fp: str) -> None:
+        self._set_state(self._items[fp], "merged")
+
+    def mark_cooldown(self, fp: str, current_iteration: int,
+                      cooldown_iterations: int) -> None:
+        o = self._items[fp]
+        self._set_state(o, "cooldown")
+        o.cooldown_until = current_iteration + cooldown_iterations
+
+    def record_attempt_failure(self, fp: str, current_iteration: int,
+                               cooldown_iterations: int, max_attempts: int) -> None:
+        o = self._items[fp]
+        o.attempt_count += 1
+        if o.attempt_count >= max_attempts:
+            self._set_state(o, "expired")
+            o.cooldown_until = None
+        else:
+            self.mark_cooldown(fp, current_iteration, cooldown_iterations)
+
+    def to_dict(self) -> dict:
+        return {fp: asdict(o) for fp, o in self._items.items()}
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Ledger":
+        led = cls()
+        for fp, raw in d.items():
+            led._items[fp] = Opportunity(**raw)
+        return led

cih/merge_queue.py

@@ -0,0 +1,37 @@
+# cih/merge_queue.py
+from dataclasses import dataclass, field
+from typing import Callable, Optional
+
+@dataclass
+class MergeOutcome:
+    merged: list = field(default_factory=list)
+    rejected: list = field(default_factory=list)
+    final_base_sha: str = ""
+
+def order_by_overlap(charters: list[dict]) -> list[dict]:
+    # cheap precheck: fewer intended files -> integrate earlier (less collision surface)
+    return sorted(charters,
+                  key=lambda c: len(c.get("impact_manifest", {}).get("intended_files", [])))
+
+def integrate(teams: list[tuple], base_sha: str,
+              reverify: Callable[[str, str], tuple[bool, Optional[str]]],
+              integration_retries: int) -> MergeOutcome:
+    """teams: list of (team_id, charter). reverify(team_id, base)->(ok, new_base_sha)
+    re-runs the full suite + execution-reviewer on the rebased branch and returns
+    the real new base SHA on success."""
+    ordered_ids = [c["id"] for c in order_by_overlap([c for _, c in teams])]
+    by_id = dict(teams)
+    outcome = MergeOutcome(final_base_sha=base_sha)
+    for team_id in ordered_ids:
+        new_base_sha = None
+        for _ in range(integration_retries + 1):
+            ok, candidate = reverify(team_id, outcome.final_base_sha)
+            if ok:
+                new_base_sha = candidate
+                break
+        if new_base_sha is not None:
+            outcome.merged.append(team_id)
+            outcome.final_base_sha = new_base_sha
+        else:
+            outcome.rejected.append(team_id)
+    return outcome