cortex-loop 0.1.0a1__py3-none-any.whl

cortex/retry.py

@@ -0,0 +1,312 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+RETRYABLE_STATUSES: frozenset[str] = frozenset({"error", "failed", "fail"})
+NON_RETRYABLE_REASONS: frozenset[str] = frozenset({"invariant_violation", "stop_gate_failure", "policy_violation", "challenge_failure", "permission_denied", "authentication_failure"})
+CORRECTIVE_RETRYABLE: str = "corrective_retryable"
+TERMINAL_HARD_GATE: str = "terminal_hard_gate"
+_CORRECTIVE_CANONICAL: frozenset[str] = frozenset({"tool_error", "timeout", "shape_mismatch", "range_error", "format_error"})
+_REASON_RETRY_LIMITS: Mapping[str, int] = {
+    "timeout": 3,
+    "tool_error": 3,
+    "shape_mismatch": 2,
+    "format_error": 2,
+    "range_error": 1,
+}
+_DELTA_OBJECTIVE_KEYS: tuple[str, ...] = ("changed_files", "updated_files")
+_DELTA_SENSITIVE_REASONS: frozenset[str] = frozenset({"shape_mismatch", "range_error", "format_error"})
+
+
+@dataclass(slots=True)
+class FailureVerdict:
+    retryable: bool
+    reason: str
+    hard_stop: bool = False
+
+
+@dataclass(slots=True)
+class RetryVerdict:
+    should_retry: bool
+    hard_stop: bool
+    failure_class: str
+    reason: str
+    budget_remaining: int
+    budget_exhausted: bool
+    decision_code: str
+    failure_signature: str
+
+
+def compute_retry_verdict(
+    *,
+    store: Any,
+    session_id: str,
+    payload: Mapping[str, Any],
+    max_retries: int,
+) -> RetryVerdict | None:
+    failure = classify_failure(payload)
+    if failure is None:
+        return None
+    reason = failure.reason
+    reason_limit = reason_retry_limit(reason, default_limit=max_retries)
+    attempts_state = store.get_retry_attempts(session_id, reason=reason)
+    budget_state = _retry_budget_state(
+        attempts=int(attempts_state["attempts"]),
+        reason_attempts=int(attempts_state["reason_attempts"]),
+        max_retries=max_retries,
+        reason_limit=reason_limit,
+    )
+    signature = failure_signature(payload, reason=reason)
+    delta_hash = objective_delta_hash(payload)
+    delta_sensitive = reason in _DELTA_SENSITIVE_REASONS
+    previous_delta_hash = (
+        store.get_retry_delta_hash(session_id, reason, signature)
+        if delta_sensitive
+        else None
+    )
+    remaining_session = int(budget_state["remaining"])
+    remaining_reason = int(budget_state["reason_remaining"])
+    remaining = int(budget_state["budget_remaining"])
+    terminal_code = (
+        "hard_stop"
+        if failure.hard_stop
+        else "reason_budget_exhausted"
+        if remaining_reason <= 0
+        else "session_budget_exhausted"
+        if remaining_session <= 0
+        else ""
+    )
+    if terminal_code:
+        return RetryVerdict(
+            should_retry=False,
+            hard_stop=terminal_code == "hard_stop",
+            failure_class=TERMINAL_HARD_GATE if terminal_code == "hard_stop" else CORRECTIVE_RETRYABLE,
+            reason=reason,
+            budget_remaining=remaining,
+            budget_exhausted=remaining == 0 or terminal_code != "hard_stop",
+            decision_code=terminal_code,
+            failure_signature=signature,
+        )
+
+    if delta_sensitive and previous_delta_hash is not None and not previous_delta_hash and not delta_hash:
+        store.upsert_retry_delta_hash(
+            session_id,
+            reason=reason,
+            failure_signature=signature,
+            delta_hash=delta_hash,
+        )
+        return RetryVerdict(
+            should_retry=False,
+            hard_stop=False,
+            failure_class=CORRECTIVE_RETRYABLE,
+            reason=reason,
+            budget_remaining=remaining,
+            budget_exhausted=remaining == 0,
+            decision_code="no_delta",
+            failure_signature=signature,
+        )
+
+    outcome = _consume_retry_with_budget(
+        store=store,
+        session_id=session_id,
+        reason=reason,
+        max_retries=max_retries,
+        reason_limit=reason_limit,
+    )
+    if delta_sensitive:
+        store.upsert_retry_delta_hash(
+            session_id,
+            reason=reason,
+            failure_signature=signature,
+            delta_hash=delta_hash,
+        )
+    return RetryVerdict(
+        should_retry=bool(outcome["consumed"]),
+        hard_stop=False,
+        failure_class=CORRECTIVE_RETRYABLE,
+        reason=reason,
+        budget_remaining=int(outcome["budget_remaining"]),
+        budget_exhausted=bool(outcome["budget_exhausted"]),
+        decision_code=str(outcome["decision_code"]),
+        failure_signature=signature,
+    )
+
+
+def reason_retry_limit(reason: str, *, default_limit: int) -> int:
+    return max(0, min(default_limit, int(_REASON_RETRY_LIMITS.get(reason, default_limit))))
+
+
+def _retry_budget_state(
+    *,
+    attempts: int,
+    reason_attempts: int,
+    max_retries: int,
+    reason_limit: int,
+) -> dict[str, int | str]:
+    session_limit = max(0, int(max_retries))
+    reason_cap = max(0, int(reason_limit))
+    session_attempts = max(0, int(attempts))
+    reason_attempts = max(0, int(reason_attempts))
+    remaining = max(0, session_limit - session_attempts)
+    reason_remaining = max(0, reason_cap - reason_attempts)
+    decision_code = "retry_allowed"
+    if remaining <= 0:
+        decision_code = "session_budget_exhausted"
+    elif reason_remaining <= 0:
+        decision_code = "reason_budget_exhausted"
+    return {
+        "attempts": session_attempts,
+        "reason_attempts": reason_attempts,
+        "remaining": remaining,
+        "reason_remaining": reason_remaining,
+        "budget_remaining": min(remaining, reason_remaining),
+        "decision_code": decision_code,
+    }
+
+
+def _consume_retry_with_budget(
+    *,
+    store: Any,
+    session_id: str,
+    reason: str,
+    max_retries: int,
+    reason_limit: int,
+) -> dict[str, int | bool | str]:
+    for _ in range(16):
+        attempts_state = store.get_retry_attempts(session_id, reason=reason)
+        state = _retry_budget_state(
+            attempts=int(attempts_state["attempts"]),
+            reason_attempts=int(attempts_state["reason_attempts"]),
+            max_retries=max_retries,
+            reason_limit=reason_limit,
+        )
+        if state["decision_code"] != "retry_allowed":
+            return {
+                "consumed": False,
+                "attempts": int(state["attempts"]),
+                "reason_attempts": int(state["reason_attempts"]),
+                "budget_remaining": int(state["budget_remaining"]),
+                "decision_code": str(state["decision_code"]),
+                "budget_exhausted": True,
+            }
+
+        write_outcome = store.try_increment_retry_attempts(
+            session_id,
+            reason=reason,
+            expected_attempts=int(state["attempts"]),
+            expected_reason_attempts=int(state["reason_attempts"]),
+        )
+        if bool(write_outcome["consumed"]):
+            post = _retry_budget_state(
+                attempts=int(write_outcome["attempts"]),
+                reason_attempts=int(write_outcome["reason_attempts"]),
+                max_retries=max_retries,
+                reason_limit=reason_limit,
+            )
+            return {
+                "consumed": True,
+                "attempts": int(post["attempts"]),
+                "reason_attempts": int(post["reason_attempts"]),
+                "budget_remaining": int(post["budget_remaining"]),
+                "decision_code": "retry_allowed",
+                "budget_exhausted": int(post["budget_remaining"]) == 0,
+            }
+
+    final_attempts = store.get_retry_attempts(session_id, reason=reason)
+    final_state = _retry_budget_state(
+        attempts=int(final_attempts["attempts"]),
+        reason_attempts=int(final_attempts["reason_attempts"]),
+        max_retries=max_retries,
+        reason_limit=reason_limit,
+    )
+    return {
+        "consumed": False,
+        "attempts": int(final_state["attempts"]),
+        "reason_attempts": int(final_state["reason_attempts"]),
+        "budget_remaining": int(final_state["budget_remaining"]),
+        "decision_code": (
+            str(final_state["decision_code"])
+            if final_state["decision_code"] != "retry_allowed"
+            else "retry_contention"
+        ),
+        "budget_exhausted": final_state["decision_code"] != "retry_allowed",
+    }
+
+
+def objective_delta_hash(payload: Mapping[str, Any]) -> str:
+    files = _collect_objective_delta_files(payload)
+    if not files:
+        return ""
+    return hashlib.sha256(
+        json.dumps(files, separators=(",", ":"), ensure_ascii=True).encode("utf-8")
+    ).hexdigest()
+
+
+def failure_signature(payload: Mapping[str, Any], *, reason: str) -> str:
+    canonical = {
+        "reason": reason,
+        "tool_name": _normalize_token(payload.get("tool_name")),
+        "status": _normalize_token(payload.get("status")),
+        "message": _normalize_token(payload.get("error") or payload.get("message") or payload.get("stderr"))[:240],
+        "target_files": _normalize_files(payload.get("target_files")),
+        "planned_files": _normalize_files(payload.get("planned_files")),
+    }
+    return hashlib.sha256(
+        json.dumps(canonical, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).hexdigest()
+
+
+def _canonical_reason(raw_reason: Any) -> str:
+    token = re.sub(r"[^a-z0-9_]+", "_", re.sub(r"[\s\-]+", "_", str(raw_reason or "").lower().strip())).strip("_")
+    if not token or token in _CORRECTIVE_CANONICAL:
+        return token
+    parts = set(token.split("_"))
+    if {"shape", "mismatch"} <= parts:
+        return "shape_mismatch"
+    if {"range", "error"} <= parts:
+        return "range_error"
+    if {"format", "error"} <= parts:
+        return "format_error"
+    return "timeout" if "timeout" in parts else token
+
+
+def classify_failure(payload: Mapping[str, Any]) -> FailureVerdict | None:
+    if str(payload.get("status", "")).lower().strip() not in RETRYABLE_STATUSES:
+        return None
+    reason = _canonical_reason(payload.get("failure_reason") or payload.get("reason"))
+    if reason in NON_RETRYABLE_REASONS:
+        return FailureVerdict(retryable=False, reason=reason, hard_stop=True)
+    if not reason:
+        inferred = _canonical_reason(payload.get("error") or payload.get("message") or payload.get("stderr"))
+        if inferred in _CORRECTIVE_CANONICAL:
+            return FailureVerdict(retryable=True, reason=inferred)
+        return FailureVerdict(retryable=True, reason="tool_error")
+    if reason in _CORRECTIVE_CANONICAL:
+        return FailureVerdict(retryable=True, reason=reason)
+    return FailureVerdict(retryable=False, reason=reason, hard_stop=True)
+
+
+def _normalize_token(value: Any) -> str:
+    return re.sub(r"\s+", " ", str(value or "").strip().lower())
+
+
+def _normalize_files(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    tokens = [str(item).strip() for item in value]
+    return sorted({token for token in tokens if token})
+
+
+def _collect_objective_delta_files(payload: Mapping[str, Any]) -> list[str]:
+    files: list[str] = []
+    for key in _DELTA_OBJECTIVE_KEYS:
+        value = payload.get(key)
+        if not isinstance(value, list):
+            continue
+        files.extend(str(item).strip() for item in value)
+    return sorted({token for token in files if token})

cortex/stop_contract.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from .stop_payload import extract_stop_fields, resolve_stop_value
+from .utils import _as_string_list
+
+STOP_PAYLOAD_KEYS = (
+    "challenge_coverage",
+    "requirement_audit",
+    "truth_claims",
+    "required_requirement_ids",
+    "failed_approach",
+    "stuck_declaration",
+)
+
+
+@dataclass(slots=True)
+class StopContract:
+    warnings: list[str]
+    stop_source: str
+    stop_fields_source: str
+    stop_fields_fallback_used: bool
+    stop_key_normalization_count: int
+    challenge_coverage: Any
+    requirement_audit: Any
+    truth_claims: Any
+    required_requirement_ids: list[str]
+    failed_approach: dict[str, Any] | None
+    stuck_declaration: dict[str, Any] | None
+    structured_stop_violation: bool
+    contract_diagnostic: dict[str, Any] | None
+
+
+def resolve_stop_contract(
+    payload: Mapping[str, Any],
+    *,
+    allow_message_fallback: bool,
+    require_structured_stop_payload: bool,
+) -> StopContract:
+    stop_fields, stop_fields_source, warnings, normalization_count = extract_stop_fields(
+        payload, allow_message_fallback=allow_message_fallback
+    )
+    values = {
+        key: resolve_stop_value(
+            key=key,
+            payload=payload,
+            stop_fields=stop_fields,
+            stop_fields_source=stop_fields_source,
+            warnings=warnings,
+            value_label=key,
+        )
+        for key in STOP_PAYLOAD_KEYS
+    }
+    stop_source = _stop_source_label(stop_fields_source)
+    used_message_stop_fallback = bool(stop_source == "message_fallback" and stop_fields is not None)
+    if used_message_stop_fallback:
+        warnings.append(
+            "Recovered stop fields from last_assistant_message STOP_FIELDS_JSON fallback; emit structured stop fields directly."
+        )
+    if normalization_count > 0:
+        warnings.append(
+            f"Canonicalized {normalization_count} stop payload key(s) with surrounding whitespace."
+        )
+    has_structured_stop_source = _has_structured_stop_source(payload, stop_fields_source)
+    structured_stop_violation = bool(require_structured_stop_payload and not has_structured_stop_source)
+    contract_diagnostic = None
+    if structured_stop_violation:
+        if used_message_stop_fallback:
+            warnings.append(
+                "Structured stop payload is required; trailer-only STOP_FIELDS_JSON fallback is rejected."
+            )
+            contract_diagnostic = structured_stop_contract_diagnostic("trailer_fallback_rejected")
+        else:
+            warnings.append(
+                "Structured stop payload is required; include stop fields directly or via payload.stop_fields."
+            )
+            contract_diagnostic = structured_stop_contract_diagnostic("missing_structured_stop_fields")
+
+    return StopContract(
+        warnings=warnings,
+        stop_source=stop_source,
+        stop_fields_source=stop_fields_source or "none",
+        stop_fields_fallback_used=used_message_stop_fallback,
+        stop_key_normalization_count=normalization_count,
+        challenge_coverage=values["challenge_coverage"],
+        requirement_audit=values["requirement_audit"],
+        truth_claims=values["truth_claims"],
+        required_requirement_ids=_as_string_list(values["required_requirement_ids"]),
+        failed_approach=_resolve_failed_approach(payload, values["failed_approach"], stop_fields=stop_fields),
+        stuck_declaration=_resolve_stuck_declaration(
+            values["stuck_declaration"],
+            warnings=warnings,
+        ),
+        structured_stop_violation=structured_stop_violation,
+        contract_diagnostic=contract_diagnostic,
+    )
+
+
+def _resolve_failed_approach(
+    payload: Mapping[str, Any],
+    failed_approach: Any,
+    *,
+    stop_fields: Mapping[str, Any] | None = None,
+) -> dict[str, Any] | None:
+    summary = ""
+    reason = ""
+    files: list[str] = []
+
+    if isinstance(failed_approach, Mapping):
+        summary = str(
+            failed_approach.get("summary")
+            or failed_approach.get("what_was_tried")
+            or failed_approach.get("approach")
+            or ""
+        ).strip()
+        reason = str(failed_approach.get("reason") or failed_approach.get("why_failed") or "").strip()
+        files = _as_string_list(failed_approach.get("files"))
+    elif isinstance(failed_approach, str):
+        summary = failed_approach.strip()
+
+    if not summary:
+        for key in ("what_was_tried", "failed_summary", "approach", "failed_approach_summary"):
+            candidate = str(payload.get(key) or (stop_fields or {}).get(key) or "").strip()
+            if candidate:
+                summary = candidate
+                break
+    if not reason:
+        for key in ("why_failed", "failure_reason", "reason"):
+            candidate = str(payload.get(key) or (stop_fields or {}).get(key) or "").strip()
+            if candidate:
+                reason = candidate
+                break
+    if not files:
+        files = (
+            _as_string_list(payload.get("failed_files"))
+            or _as_string_list(payload.get("files"))
+            or _as_string_list(payload.get("target_files"))
+            or _as_string_list((stop_fields or {}).get("failed_files"))
+            or _as_string_list((stop_fields or {}).get("files"))
+            or _as_string_list((stop_fields or {}).get("target_files"))
+        )
+
+    if not summary or not reason:
+        return None
+    return {"summary": summary, "reason": reason, "files": files}
+
+
+def _resolve_stuck_declaration(
+    value: Any,
+    *,
+    warnings: list[str],
+) -> dict[str, Any] | None:
+    if value is None:
+        return None
+    if not isinstance(value, Mapping):
+        warnings.append("Ignoring invalid stuck_declaration; expected an object.")
+        return None
+
+    check = str(value.get("check") or "").strip()
+    approaches_tried = _as_string_list(value.get("approaches_tried"))
+    obstacle = str(value.get("obstacle") or "").strip()
+    if not (check and approaches_tried and obstacle):
+        warnings.append(
+            "Ignoring incomplete stuck_declaration; expected check, approaches_tried, and obstacle."
+        )
+        return None
+
+    return {
+        "check": check,
+        "approaches_tried": approaches_tried,
+        "obstacle": obstacle,
+    }
+
+
+def reconcile_required_requirement_ids(
+    session_required_ids: list[str], stop_required_ids: list[str]
+) -> tuple[list[str], str, str | None]:
+    if session_required_ids:
+        warning = (
+            "Ignoring required_requirement_ids from Stop payload; using SessionStart contract."
+            if stop_required_ids and set(stop_required_ids) != set(session_required_ids)
+            else None
+        )
+        return list(session_required_ids), "session", warning
+    if stop_required_ids:
+        return (
+            list(stop_required_ids),
+            "stop_payload",
+            "No SessionStart requirement contract found; using Stop-provided required_requirement_ids.",
+        )
+    return [], "none", None
+
+
+def _stop_source_label(stop_fields_source: str | None) -> str:
+    if stop_fields_source == "last_assistant_message":
+        return "message_fallback"
+    if stop_fields_source == "payload.stop_fields":
+        return "payload.stop_fields"
+    return "native"
+
+
+def _has_structured_stop_source(payload: Mapping[str, Any], stop_fields_source: str | None) -> bool:
+    return bool(
+        any(payload.get(key) is not None for key in STOP_PAYLOAD_KEYS)
+        or stop_fields_source == "payload.stop_fields"
+    )
+
+
+def structured_stop_contract_diagnostic(kind: str) -> dict[str, Any]:
+    if kind == "trailer_fallback_rejected":
+        return {"evidence_found": ["stop fields only via last_assistant_message STOP_FIELDS_JSON trailer"], "evidence_expected": ["native structured stop fields or payload.stop_fields"], "gap_description": "Structured stop evidence was only provided through trailer fallback.", "gap_characterization": "execution_gap", "distance_signal": "close"}
+    if kind == "strict_message_fallback_rejected":
+        return {"evidence_found": ["stop_source=message_fallback"], "evidence_expected": ["stop_source=native or payload.stop_fields"], "gap_description": "Strict mode rejected message-fallback stop evidence.", "gap_characterization": "execution_gap", "distance_signal": "close"}
+    return {"evidence_found": ["no machine-readable stop fields"], "evidence_expected": ["native structured stop fields or payload.stop_fields"], "gap_description": "Completion was claimed without machine-readable stop evidence.", "gap_characterization": "comprehension_gap", "distance_signal": "far"}

cortex/stop_payload.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from typing import Any
+
+STOP_FIELD_KEYS = (
+    "challenge_coverage",
+    "requirement_audit",
+    "truth_claims",
+    "required_requirement_ids",
+    "failed_approach",
+    "stuck_declaration",
+)
+
+
+def extract_stop_fields(
+    payload: Mapping[str, Any], *, allow_message_fallback: bool = True
+) -> tuple[dict[str, Any] | None, str | None, list[str], int]:
+    warnings: list[str] = []
+
+    raw = payload.get("stop_fields")
+    if isinstance(raw, Mapping):
+        normalized, normalization_count = _canonicalize_map_keys(raw)
+        return normalized, "payload.stop_fields", warnings, normalization_count
+    if raw is not None:
+        warnings.append("Ignoring invalid stop_fields field; expected an object.")
+
+    if not allow_message_fallback:
+        return None, None, warnings, 0
+    if any(payload.get(key) is not None for key in STOP_FIELD_KEYS):
+        return None, None, warnings, 0
+
+    last_message = payload.get("last_assistant_message")
+    if isinstance(last_message, str):
+        parsed, marker_found, error = parse_stop_fields_json(last_message)
+        if parsed is not None:
+            normalized, normalization_count = _canonicalize_map_keys(parsed)
+            return normalized, "last_assistant_message", warnings, normalization_count
+        if marker_found and error:
+            warnings.append(f"Ignoring invalid STOP_FIELDS_JSON trailer: {error}")
+
+    return None, None, warnings, 0
+
+
+def resolve_stop_value(
+    *,
+    key: str,
+    payload: Mapping[str, Any],
+    stop_fields: dict[str, Any] | None,
+    stop_fields_source: str | None,
+    warnings: list[str],
+    value_label: str,
+) -> Any:
+    value = payload.get(key)
+    if value is not None or not (stop_fields and key in stop_fields):
+        return value
+    value = stop_fields[key]
+    if stop_fields_source == "last_assistant_message":
+        warnings.append(f"Using {value_label} parsed from last assistant message (STOP_FIELDS_JSON).")
+    elif stop_fields_source == "payload.stop_fields":
+        warnings.append(f"Using {value_label} from payload.stop_fields.")
+    return value
+
+
+def parse_stop_fields_json(text: str) -> tuple[dict[str, Any] | None, bool, str | None]:
+    for pattern in (
+        r"```(?:stop-fields|stop_fields)\s*(\{.*?\})\s*```",
+        r"```json\s*(\{.*?\"challenge_coverage\".*?\})\s*```",
+    ):
+        match = re.search(pattern, text, flags=re.DOTALL)
+        if not match:
+            continue
+        try:
+            parsed = json.loads(match.group(1))
+        except json.JSONDecodeError as exc:
+            return None, True, str(exc)
+        if not isinstance(parsed, dict):
+            return None, True, "expected a JSON object"
+        return parsed, True, None
+
+    marker = "STOP_FIELDS_JSON:"
+    idx = text.rfind(marker)
+    if idx == -1:
+        return None, False, None
+    decoder = json.JSONDecoder()
+    try:
+        parsed, _ = decoder.raw_decode(text[idx + len(marker) :].lstrip())
+    except json.JSONDecodeError as exc:
+        return None, True, str(exc)
+    if not isinstance(parsed, dict):
+        return None, True, "expected a JSON object"
+    return parsed, True, None
+
+
+def _canonicalize_map_keys(value: Mapping[str, Any]) -> tuple[dict[str, Any], int]:
+    normalized: dict[str, Any] = {}
+    normalization_count = 0
+    for raw_key, raw_value in value.items():
+        key = str(raw_key)
+        canonical_key = key.strip()
+        if canonical_key != key:
+            normalization_count += 1
+        canonical_value, nested_count = _canonicalize_value(raw_value)
+        normalization_count += nested_count
+        normalized[canonical_key] = canonical_value
+    return normalized, normalization_count
+
+
+def _canonicalize_value(value: Any) -> tuple[Any, int]:
+    if isinstance(value, Mapping):
+        return _canonicalize_map_keys(value)
+    if isinstance(value, list):
+        items: list[Any] = []
+        normalization_count = 0
+        for item in value:
+            canonical_item, nested_count = _canonicalize_value(item)
+            items.append(canonical_item)
+            normalization_count += nested_count
+        return items, normalization_count
+    return value, 0