constraintloop 0.1.0__py3-none-any.whl

constraintloop/hooks.py

@@ -0,0 +1,335 @@
+"""Normalize agent hook payloads into one constraint lifecycle."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from constraintloop.config import ContractError, load_contract
+from constraintloop.engine import ConstraintEngine, blocking_results, format_summary
+from constraintloop.loops import run_cycle
+from constraintloop.models import LoopState, Phase, Verdict
+from constraintloop.state import advisory_acknowledgment_reason, load_session, save_session
+
+
+def handle_hook(
+    project_root: Path,
+    adapter: str,
+    event: str,
+    payload: dict[str, Any],
+) -> dict[str, Any]:
+    session_id = str(
+        payload.get("session_id")
+        or payload.get("sessionId")
+        or payload.get("conversation_id")
+        or "default"
+    )
+    state = load_session(project_root, session_id)
+
+    if event == "user-prompt":
+        prompt = payload.get("prompt") or payload.get("user_prompt")
+        if not prompt and isinstance(payload.get("input"), str):
+            prompt = payload["input"]
+        if isinstance(prompt, str) and prompt.strip():
+            if _is_hook_feedback(prompt):
+                state["last_hook_feedback"] = prompt.strip()[-8000:]
+                save_session(project_root, session_id, state)
+                return _context_response(
+                    adapter, event, "ConstraintLoop captured evaluator feedback."
+                )
+            state["goal"] = prompt.strip()[-8000:]
+            save_session(project_root, session_id, state)
+        return _context_response(adapter, event, "ConstraintLoop captured the task goal.")
+
+    if event == "pre-tool":
+        serialized = json.dumps(
+            payload.get("tool_input", payload.get("toolInput", payload)),
+            sort_keys=True,
+        )
+        if _protected_mutation(payload, serialized):
+            return _deny_response(
+                adapter,
+                "Agent writes to protected quality policy or creates a local exception. "
+                "Ask the human to make this change outside the agent session.",
+            )
+        return {}
+
+    try:
+        contract, _ = load_contract(project_root)
+    except ContractError as exc:
+        if event == "stop":
+            return _block_response(adapter, str(exc))
+        return _context_response(adapter, event, str(exc))
+
+    if event == "session-start":
+        required = [
+            constraint_id
+            for constraint_id, spec in contract.constraints.items()
+            if spec.enabled and spec.enforcement.value == "required"
+        ]
+        return _context_response(
+            adapter,
+            event,
+            "ConstraintLoop completion contract is active. Required gates: "
+            + (", ".join(required) if required else "none")
+            + ". Do not edit the contract or create waivers.",
+        )
+
+    if event == "post-tool":
+        record = ConstraintEngine(
+            project_root,
+            contract,
+            goal=state.get("goal"),
+            agent_adapter=adapter,
+        ).run(Phase.CHANGE)
+        if record.results:
+            return _context_response(adapter, event, format_summary(record))
+        return {}
+
+    if event == "pre-compact":
+        return _context_response(
+            adapter,
+            event,
+            "ConstraintLoop remains authoritative at completion. Run or repair all required "
+            "stop gates before claiming the task is complete.",
+        )
+
+    if event != "stop":
+        return {}
+
+    record = ConstraintEngine(
+        project_root,
+        contract,
+        goal=state.get("goal"),
+        agent_adapter=adapter,
+    ).run(Phase.STOP)
+    failures = blocking_results(record)
+    completion_loop = next(
+        (loop_name for loop_name, config in contract.loops.items() if config.phase == Phase.STOP),
+        None,
+    )
+    cycle = (
+        run_cycle(
+            project_root,
+            contract,
+            completion_loop,
+            record=record,
+            goal=state.get("goal"),
+            agent_adapter=adapter,
+        )
+        if completion_loop is not None
+        else None
+    )
+    advisories = [
+        result
+        for result in record.results
+        if not result.blocks
+        and result.verdict
+        not in {
+            Verdict.PASS,
+            Verdict.SKIPPED,
+            Verdict.WAIVED,
+        }
+    ]
+    if not failures:
+        state["attempts"] = 0
+        state.pop("failed_snapshot", None)
+        if advisories:
+            snapshot = _result_snapshot(advisories)
+            summary = format_summary(record, include_output=True)
+            if state.get("advisory_feedback_snapshot") != snapshot:
+                state["advisory_feedback_snapshot"] = snapshot
+                save_session(project_root, session_id, state)
+                return _block_response(
+                    adapter,
+                    summary
+                    + "\nAdvisory feedback requires an agent disposition. Address it until fresh "
+                    "evidence passes, or record why no change is appropriate with "
+                    '`constraintloop acknowledge CONSTRAINT --reason "..."`, then try '
+                    "completion again.",
+                )
+            reasons = {
+                result.constraint_id: advisory_acknowledgment_reason(project_root, result)
+                for result in advisories
+            }
+            missing = [constraint_id for constraint_id, reason in reasons.items() if not reason]
+            if missing:
+                return _block_response(
+                    adapter,
+                    summary
+                    + "\nAdvisory feedback was delivered but has no snapshot-bound disposition "
+                    f"for: {', '.join(missing)}. Address it or explicitly acknowledge it.",
+                )
+            save_session(project_root, session_id, state)
+            return _allow_response(
+                adapter,
+                summary
+                + "\nAdvisory feedback was explicitly acknowledged for this exact evidence: "
+                + "; ".join(
+                    f"{constraint_id}: {reason}" for constraint_id, reason in reasons.items()
+                ),
+            )
+        state.pop("advisory_feedback_snapshot", None)
+        save_session(project_root, session_id, state)
+        return _allow_response(adapter, format_summary(record, include_output=True))
+
+    if cycle is not None:
+        summary = format_summary(record, include_output=True)
+        detail = (
+            f"\nLoop {cycle.loop}: {cycle.state.value}; "
+            f"repair attempt {cycle.repair_attempt}. {cycle.next_action}"
+        )
+        if cycle.state in {LoopState.REPAIR, LoopState.WAITING}:
+            return _block_response(adapter, summary + detail)
+        return _human_required_response(adapter, summary + detail)
+
+    snapshot = _result_snapshot(failures)
+    attempts = int(state.get("attempts", 0)) + 1 if state.get("failed_snapshot") == snapshot else 1
+    state["attempts"] = attempts
+    state["failed_snapshot"] = snapshot
+    save_session(project_root, session_id, state)
+    summary = format_summary(record, include_output=True)
+    if attempts <= contract.settings.max_auto_retries:
+        return _block_response(
+            adapter,
+            summary + f"\nRepair the failures and try again "
+            f"({attempts}/{contract.settings.max_auto_retries} automatic retries).",
+        )
+    return _human_required_response(
+        adapter,
+        summary + "\nThe same evidence failed repeatedly. Stop automatic repair and ask a human "
+        "to fix the implementation, revise the contract, or create a local waiver.",
+    )
+
+
+def _result_snapshot(results: list[Any]) -> str:
+    return hashlib.sha256(
+        json.dumps(
+            [(item.constraint_id, item.input_digest, item.verdict.value) for item in results],
+            sort_keys=True,
+        ).encode()
+    ).hexdigest()
+
+
+_NATIVE_EVENTS = {
+    "claude": {
+        "session-start": "SessionStart",
+        "user-prompt": "UserPromptSubmit",
+        "post-tool": "PostToolUse",
+        "pre-compact": "PreCompact",
+        "stop": "Stop",
+    },
+    "codex": {
+        "session-start": "SessionStart",
+        "user-prompt": "UserPromptSubmit",
+        "post-tool": "PostToolUse",
+        "pre-compact": "PreCompact",
+        "stop": "Stop",
+    },
+    "gemini": {
+        "session-start": "SessionStart",
+        "user-prompt": "BeforeAgent",
+        "post-tool": "AfterTool",
+        "pre-compact": "PreCompress",
+        "stop": "AfterAgent",
+    },
+}
+
+
+def _context_response(adapter: str, event: str, text: str) -> dict[str, Any]:
+    native_event = _NATIVE_EVENTS[adapter].get(event)
+    if event == "pre-compact" and adapter in {"claude", "codex"}:
+        return {"systemMessage": text}
+    if native_event is None:
+        return {"systemMessage": text}
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": native_event,
+            "additionalContext": text,
+        }
+    }
+
+
+def _deny_response(adapter: str, reason: str) -> dict[str, Any]:
+    if adapter == "gemini":
+        return {"decision": "deny", "reason": reason}
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": reason,
+        }
+    }
+
+
+def _block_response(adapter: str, reason: str) -> dict[str, Any]:
+    if adapter == "gemini":
+        return {"decision": "deny", "reason": reason}
+    return {"decision": "block", "reason": reason}
+
+
+def _allow_response(adapter: str, summary: str) -> dict[str, Any]:
+    if adapter == "gemini":
+        return {"decision": "allow", "systemMessage": summary}
+    return {"continue": True, "systemMessage": summary}
+
+
+def _human_required_response(adapter: str, reason: str) -> dict[str, Any]:
+    if adapter == "gemini":
+        return {"decision": "deny", "reason": reason}
+    return {"continue": False, "stopReason": reason, "systemMessage": reason}
+
+
+def _is_hook_feedback(prompt: str) -> bool:
+    stripped = prompt.strip()
+    return stripped.startswith("<hook_prompt ") and stripped.endswith("</hook_prompt>")
+
+
+def _protected_mutation(payload: dict[str, Any], serialized: str) -> bool:
+    protected = (
+        "constraintloop." + "yml",
+        "constraintloop." + "yaml",
+        ".constraintloop/" + "secrets.env",
+    )
+    tool_name = str(payload.get("tool_name") or payload.get("toolName") or "").lower()
+    tool_input = payload.get("tool_input", payload.get("toolInput", payload))
+    if not isinstance(tool_input, dict):
+        tool_input = {}
+    text_values = [value for value in tool_input.values() if isinstance(value, str)]
+    if "patch" in tool_name or any(value.startswith("*** Begin Patch") for value in text_values):
+        headers = re.findall(
+            r"^\*\*\* (?:Add File|Update File|Delete File|Move to): (.+)$",
+            "\n".join(text_values),
+            re.MULTILINE,
+        )
+        return any(any(name in header for name in protected) for header in headers)
+    command = tool_input.get("cmd") or tool_input.get("command")
+    if isinstance(command, str):
+        forbidden_subcommand = "constraintloop " + "waive"
+        if forbidden_subcommand in command:
+            return True
+        mutator = re.search(
+            r"(^|[;&|]\s*)(rm|mv|cp|tee|touch|truncate|sed\s+-i|perl\s+-i)\b|[>]",
+            command,
+        )
+        if mutator and any(name in command for name in protected):
+            return True
+    if any("*** " in value for value in text_values):
+        headers = re.findall(
+            r"^\*\*\* (?:Add File|Update File|Delete File|Move to): (.+)$",
+            "\n".join(text_values),
+            re.MULTILINE,
+        )
+        return any(any(name in header for name in protected) for header in headers)
+    if any(marker in tool_name for marker in ("write", "edit", "delete", "move")):
+        path_values = [
+            value
+            for key, value in tool_input.items()
+            if key.lower() in {"path", "file_path", "filepath", "destination", "target"}
+            and isinstance(value, str)
+        ]
+        return any(any(name in value for name in protected) for value in path_values)
+    return False

constraintloop/loops.py

@@ -0,0 +1,334 @@
+"""Bounded, journaled convergence-loop transitions."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import signal
+import time
+import uuid
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+from constraintloop.config import contract_digest
+from constraintloop.digest import constraint_input_digest
+from constraintloop.engine import ConstraintEngine, blocking_results
+from constraintloop.models import (
+    Contract,
+    CycleResult,
+    EvidenceRecord,
+    LoopConfig,
+    LoopJournal,
+    LoopState,
+    Phase,
+    Verdict,
+)
+from constraintloop.state import _read_json, _write_json, _write_lock, cache_root
+
+CYCLE_EXIT_CODES = {
+    LoopState.PASSED: 0,
+    LoopState.REPAIR: 10,
+    LoopState.WAITING: 11,
+    LoopState.HUMAN_REQUIRED: 12,
+    LoopState.BUDGET_EXHAUSTED: 13,
+    LoopState.ERROR: 14,
+}
+
+
+class LoopError(RuntimeError):
+    pass
+
+
+def _safe_name(name: str) -> str:
+    safe = "".join(char if char.isalnum() or char in "-_." else "_" for char in name)
+    if not safe or safe != name:
+        raise LoopError(f"Invalid loop name {name!r}")
+    return safe
+
+
+def loop_root(project_root: Path) -> Path:
+    return cache_root(project_root) / "loops"
+
+
+def journal_path(project_root: Path, loop_name: str) -> Path:
+    return loop_root(project_root) / f"{_safe_name(loop_name)}.json"
+
+
+def lease_path(project_root: Path, loop_name: str) -> Path:
+    return loop_root(project_root) / f"{_safe_name(loop_name)}.lease.json"
+
+
+def evidence_snapshot(record: EvidenceRecord) -> str:
+    payload = [
+        {
+            "constraint_id": item.constraint_id,
+            "input_digest": item.input_digest,
+            "verdict": item.verdict.value,
+            "findings": [
+                finding.model_dump(mode="json", exclude_none=True) for finding in item.findings
+            ],
+        }
+        for item in record.results
+    ]
+    raw = json.dumps(
+        {"contract_digest": record.contract_digest, "results": payload},
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode()
+    return "sha256:" + hashlib.sha256(raw).hexdigest()
+
+
+def _input_snapshot(project_root: Path, contract: Contract, config: LoopConfig) -> str:
+    identity = contract_digest(contract)
+    inputs = [
+        (
+            constraint_id,
+            constraint_input_digest(
+                project_root,
+                constraint_id,
+                spec,
+                contract_digest=identity,
+            ),
+        )
+        for constraint_id, spec in contract.constraints.items()
+        if spec.enabled and config.phase in spec.phases
+    ]
+    return hashlib.sha256(json.dumps(inputs, sort_keys=True).encode()).hexdigest()
+
+
+def run_cycle(
+    project_root: Path,
+    contract: Contract,
+    loop_name: str,
+    *,
+    record: EvidenceRecord | None = None,
+    now: float | None = None,
+    goal: str | None = None,
+    agent_adapter: str | None = None,
+) -> CycleResult:
+    """Execute exactly one bounded transition and persist it atomically."""
+    if loop_name not in contract.loops:
+        raise LoopError(f"Unknown loop {loop_name!r}")
+    config = contract.loops[loop_name]
+    current_time = time.time() if now is None else now
+    identity = contract_digest(contract)
+    path = journal_path(project_root, loop_name)
+    with _write_lock(path):
+        raw = _read_json(path, {})
+        try:
+            journal = LoopJournal.model_validate(raw)
+        except Exception as exc:
+            if raw:
+                raise LoopError(f"Loop journal is corrupt: {path}") from exc
+            journal = LoopJournal(
+                loop=loop_name,
+                contract_digest=identity,
+                started_at=current_time,
+                updated_at=current_time,
+            )
+        if journal.contract_digest != identity:
+            journal = LoopJournal(
+                loop=loop_name,
+                contract_digest=identity,
+                started_at=current_time,
+                updated_at=current_time,
+            )
+
+        input_snapshot = _input_snapshot(project_root, contract, config)
+        last_input = journal.input_snapshot
+        if (
+            record is None
+            and journal.prior_state == LoopState.WAITING
+            and last_input == input_snapshot
+            and current_time - journal.updated_at < config.interval_seconds
+            and journal.last_result is not None
+        ):
+            previous = CycleResult.model_validate(journal.last_result)
+            result = previous.model_copy(
+                update={
+                    "observation": journal.observation + 1,
+                    "wake_after_seconds": max(
+                        0.0, config.interval_seconds - (current_time - journal.updated_at)
+                    ),
+                }
+            )
+            journal.observation = result.observation
+            journal.last_result = result.model_dump(mode="json")
+            journal.input_snapshot = input_snapshot
+            _write_json(path, journal.model_dump(mode="json"))
+            return result
+
+        if record is None:
+            record = ConstraintEngine(
+                project_root,
+                contract,
+                use_cache=config.phase != Phase.CI,
+                allow_waivers=config.phase != Phase.CI,
+                goal=goal,
+                agent_adapter=agent_adapter,
+                refresh_pending=True,
+            ).run(config.phase)
+
+        snapshot = evidence_snapshot(record)
+        observation = journal.observation + 1
+        repair_attempt = journal.repair_attempt
+        unchanged_repairs = journal.unchanged_repairs
+        if journal.prior_state == LoopState.REPAIR:
+            repair_attempt += 1
+            unchanged_repairs = unchanged_repairs + 1 if journal.prior_snapshot == snapshot else 0
+
+        required = blocking_results(record)
+        pending = [item for item in required if item.verdict == Verdict.PENDING]
+        unreliable = [
+            item for item in required if item.verdict in {Verdict.ERROR, Verdict.UNCERTAIN}
+        ]
+        blocking_ids = [item.constraint_id for item in required]
+        elapsed = current_time - journal.started_at
+
+        if not required:
+            state = LoopState.PASSED
+            action = "Fresh required evidence passes. Stop."
+            wake = 0.0
+        elif unreliable:
+            state = LoopState.ERROR
+            action = "Constraint evaluation is unreliable. Inspect evidence and require a human."
+            wake = 0.0
+        elif elapsed >= config.max_duration_seconds:
+            state = LoopState.BUDGET_EXHAUSTED
+            action = "The loop duration budget is exhausted. Require a human decision."
+            wake = 0.0
+        elif pending:
+            state = LoopState.WAITING
+            action = "Evidence is pending. Make no edits and run one cycle after the wake interval."
+            wake = config.interval_seconds
+        elif repair_attempt >= config.max_repair_attempts:
+            state = LoopState.BUDGET_EXHAUSTED
+            action = "The repair-attempt budget is exhausted. Require a human decision."
+            wake = 0.0
+        elif unchanged_repairs >= config.max_unchanged_repairs:
+            state = LoopState.HUMAN_REQUIRED
+            action = "Repairs left evidence unchanged. Require a human decision."
+            wake = 0.0
+        else:
+            state = LoopState.REPAIR
+            action = "Repair only the listed blocking constraints, then run exactly one new cycle."
+            wake = 0.0
+
+        result = CycleResult(
+            loop=loop_name,
+            state=state,
+            snapshot=snapshot,
+            observation=observation,
+            repair_attempt=repair_attempt,
+            next_action=action,
+            wake_after_seconds=wake,
+            blocking_constraints=blocking_ids,
+        )
+        journal.updated_at = current_time
+        journal.observation = observation
+        journal.repair_attempt = repair_attempt
+        journal.unchanged_repairs = unchanged_repairs
+        journal.prior_state = state
+        journal.prior_snapshot = snapshot
+        journal.input_snapshot = input_snapshot
+        journal.last_result = result.model_dump(mode="json")
+        _write_json(path, journal.model_dump(mode="json"))
+        return result
+
+
+@contextmanager
+def loop_lease(
+    project_root: Path,
+    loop_name: str,
+    *,
+    ttl_seconds: float,
+    now: float | None = None,
+) -> Iterator[Callable[[], None]]:
+    """Acquire a recoverable single-writer supervisor lease."""
+    current_time = time.time() if now is None else now
+    path = lease_path(project_root, loop_name)
+    token = str(uuid.uuid4())
+    with _write_lock(path):
+        existing = _read_json(path, {})
+        if isinstance(existing, dict) and float(existing.get("expires_at", 0)) > current_time:
+            raise LoopError(f"Loop {loop_name!r} already has an active supervisor lease")
+        _write_json(
+            path,
+            {
+                "schema_version": 1,
+                "loop": loop_name,
+                "pid": os.getpid(),
+                "token": token,
+                "expires_at": current_time + ttl_seconds,
+            },
+        )
+
+    def renew() -> None:
+        renewed_at = time.time()
+        with _write_lock(path):
+            existing = _read_json(path, {})
+            if not isinstance(existing, dict) or existing.get("token") != token:
+                raise LoopError(f"Loop {loop_name!r} supervisor lease was lost")
+            existing["expires_at"] = renewed_at + ttl_seconds
+            _write_json(path, existing)
+
+    try:
+        yield renew
+    finally:
+        with _write_lock(path):
+            existing = _read_json(path, {})
+            if isinstance(existing, dict) and existing.get("token") == token:
+                path.unlink(missing_ok=True)
+
+
+def supervise(
+    project_root: Path,
+    contract: Contract,
+    loop_name: str,
+) -> Iterator[CycleResult]:
+    """Yield state changes while waiting; return on every non-waiting state."""
+    if loop_name not in contract.loops:
+        raise LoopError(f"Unknown loop {loop_name!r}")
+    config = contract.loops[loop_name]
+    ttl = max(60.0, config.interval_seconds * 3)
+    cancelled = False
+
+    def cancel(_signum: int, _frame: Any) -> None:
+        nonlocal cancelled
+        cancelled = True
+
+    previous_handlers = {
+        signum: signal.signal(signum, cancel) for signum in (signal.SIGINT, signal.SIGTERM)
+    }
+    try:
+        with loop_lease(project_root, loop_name, ttl_seconds=ttl) as renew:
+            previous_state: LoopState | None = None
+            while not cancelled:
+                renew()
+                result = run_cycle(project_root, contract, loop_name)
+                if result.state != previous_state:
+                    yield result
+                    previous_state = result.state
+                if result.state != LoopState.WAITING:
+                    return
+                wake_at = time.monotonic() + result.wake_after_seconds
+                while not cancelled and time.monotonic() < wake_at:
+                    time.sleep(min(1.0, wake_at - time.monotonic()))
+    finally:
+        for signum, handler in previous_handlers.items():
+            signal.signal(signum, handler)
+
+
+def loop_prompt(loop_name: str, adapter: str) -> str:
+    if adapter not in {"claude", "codex"}:
+        raise LoopError(f"Unsupported loop adapter {adapter!r}")
+    return (
+        f"Run `constraintloop cycle {loop_name} --json` exactly once. Follow only its "
+        "`next_action`. Make at most one repair when state is `repair`; make no edits when "
+        "state is `waiting`. Stop on `passed`, `human_required`, `budget_exhausted`, or "
+        "`error`. Never edit the ConstraintLoop configuration or create a waiver. Repeat "
+        "only after the requested repair or wake interval."
+    )