cortex-loop 0.1.0a1__py3-none-any.whl

cortex/__init__.py

@@ -0,0 +1,7 @@
+"""Cortex Loop package."""
+
+from .core import CortexKernel
+from .hooks import marker
+
+__all__ = ["CortexKernel", "marker"]
+__version__ = "0.1.0a1"

cortex/adapters.py

@@ -0,0 +1,339 @@
+from __future__ import annotations
+
+import importlib
+import json
+import logging
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from .stop_payload import parse_stop_fields_json
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(slots=True)
+class NormalizedEvent:
+    name: str
+    payload: dict[str, Any]
+
+
+class EventAdapter(Protocol):
+    def normalize(self, event_name: str, payload: Mapping[str, Any] | None = None) -> NormalizedEvent: ...
+
+
+CANONICAL_EVENT_ALIASES = {
+    "session_start": "session_start",
+    "sessionstart": "session_start",
+    "session_marker": "session_marker",
+    "sessionmarker": "session_marker",
+    "pre_tool_use": "pre_tool_use",
+    "pretooluse": "pre_tool_use",
+    "post_tool_use": "post_tool_use",
+    "posttooluse": "post_tool_use",
+    "stop": "stop",
+}
+
+
+class GenericAdapter:
+    EVENT_ALIASES = CANONICAL_EVENT_ALIASES
+
+    def normalize(self, event_name: str, payload: Mapping[str, Any] | None = None) -> NormalizedEvent:
+        name = _normalize_event_name(event_name, self.EVENT_ALIASES)
+        data = dict(payload) if isinstance(payload, Mapping) else {}
+        return NormalizedEvent(name=name, payload=data)
+
+
+class ClaudeAdapter:
+    EVENT_ALIASES = CANONICAL_EVENT_ALIASES
+
+    def normalize(self, event_name: str, payload: Mapping[str, Any] | None = None) -> NormalizedEvent:
+        name = _normalize_event_name(event_name, self.EVENT_ALIASES)
+        data = dict(payload) if isinstance(payload, Mapping) else {}
+        data = _normalize_claude_payload(data)
+        message = data.get("last_assistant_message")
+        if isinstance(message, str):
+            rewritten = _rewrite_legacy_trailer_markers(message)
+            if name == "stop":
+                stop_fields, passthrough = _normalize_claude_stop_fields(rewritten)
+                if isinstance(stop_fields, dict):
+                    data["stop_fields"] = stop_fields
+                data["last_assistant_message"] = passthrough
+            else:
+                data["last_assistant_message"] = rewritten
+        return NormalizedEvent(name=name, payload=data)
+
+
+GEMINI_EVENT_ALIASES = {
+    **CANONICAL_EVENT_ALIASES,
+    "SessionStart": "session_start",
+    "BeforeTool": "pre_tool_use",
+    "AfterTool": "post_tool_use",
+    "AfterAgent": "stop",
+    "SessionEnd": "session_end",
+    "BeforeAgent": "before_agent",
+    "BeforeModel": "before_model",
+    "AfterModel": "after_model",
+    "BeforeToolSelection": "before_tool_selection",
+    "Notification": "notification",
+    "PreCompress": "pre_compress",
+    "sessionstart": "session_start",
+    "beforetool": "pre_tool_use",
+    "aftertool": "post_tool_use",
+    "afteragent": "stop",
+}
+
+
+class GeminiAdapter:
+    EVENT_ALIASES = GEMINI_EVENT_ALIASES
+
+    def normalize(self, event_name: str, payload: Mapping[str, Any] | None = None) -> NormalizedEvent:
+        name = _normalize_event_name(event_name, self.EVENT_ALIASES)
+        data = dict(payload) if isinstance(payload, Mapping) else {}
+        _normalize_session_id(data)
+        if name in {"pre_tool_use", "post_tool_use"}:
+            _normalize_tool_name(data, candidate_keys=("tool_name",))
+        if name == "post_tool_use":
+            _normalize_gemini_status(data)
+        if name == "stop":
+            prompt_response = data.get("prompt_response")
+            if not isinstance(prompt_response, str):
+                if "prompt_response" not in data:
+                    logger.warning("Gemini AfterAgent payload missing prompt_response; using empty string fallback.")
+                else:
+                    logger.warning(
+                        "Gemini AfterAgent prompt_response is not a string (%s); using empty string fallback.",
+                        type(prompt_response).__name__,
+                    )
+                prompt_response = ""
+            stop_fields, passthrough = _normalize_gemini_stop_fields(prompt_response)
+            data["stop_fields"] = stop_fields
+            data["last_assistant_message"] = passthrough
+        return NormalizedEvent(name=name, payload=data)
+
+
+OPENAI_EVENT_ALIASES = {
+    **CANONICAL_EVENT_ALIASES,
+    "item/commandexecution/requestapproval": "pre_tool_use",
+    "item/commandExecution/requestApproval": "pre_tool_use",
+    "command_execution_request_approval": "pre_tool_use",
+    "item/commandexecution/completed": "post_tool_use",
+    "item/commandExecution/completed": "post_tool_use",
+    "command_execution_completed": "post_tool_use",
+    "turn/completed": "stop",
+    "turn_completed": "stop",
+}
+
+
+class OpenAIAdapter:
+    EVENT_ALIASES = OPENAI_EVENT_ALIASES
+
+    def normalize(self, event_name: str, payload: Mapping[str, Any] | None = None) -> NormalizedEvent:
+        name = _normalize_event_name(event_name, self.EVENT_ALIASES)
+        data = dict(payload) if isinstance(payload, Mapping) else {}
+        _normalize_session_id(data)
+        if name in {"pre_tool_use", "post_tool_use"}:
+            _normalize_tool_name(data, candidate_keys=("tool_name", "command", "tool", "action"))
+        if name == "stop":
+            final_text = data.get("final_text")
+            if isinstance(final_text, str) and "last_assistant_message" not in data:
+                data["last_assistant_message"] = final_text
+            if "stop_fields" in data and isinstance(data.get("stop_fields"), Mapping):
+                data["stop_fields"] = dict(data["stop_fields"])
+        return NormalizedEvent(name=name, payload=data)
+
+
+def load_adapter(adapter_path: str) -> EventAdapter:
+    module_name, class_name = _split_adapter_path(adapter_path)
+    try:
+        module = importlib.import_module(module_name)
+    except Exception as exc:  # noqa: BLE001
+        raise ValueError(f"Failed to import adapter module '{module_name}': {exc}") from exc
+    adapter_cls = getattr(module, class_name, None)
+    if adapter_cls is None:
+        raise ValueError(f"Adapter class '{class_name}' not found in module '{module_name}'.")
+    try:
+        adapter = adapter_cls()
+    except Exception as exc:  # noqa: BLE001
+        raise ValueError(f"Failed to instantiate adapter '{module_name}:{class_name}': {exc}") from exc
+    if not callable(getattr(adapter, "normalize", None)):
+        raise TypeError(
+            f"Adapter '{module_name}:{class_name}' must define callable normalize(event_name, payload)."
+        )
+    return adapter
+
+
+def _split_adapter_path(adapter_path: str) -> tuple[str, str]:
+    token = str(adapter_path or "").strip()
+    if not token:
+        raise ValueError(
+            "runtime.adapter is required. Set [runtime].adapter = \"module.path:ClassName\" in cortex.toml."
+        )
+    if ":" not in token:
+        raise ValueError(
+            f"Invalid runtime.adapter '{token}'. Expected format 'module.path:ClassName'."
+        )
+    module_name, class_name = token.split(":", 1)
+    module_name = module_name.strip()
+    class_name = class_name.strip()
+    module_name = _ADAPTER_PATH_ALIASES.get(module_name, module_name)
+    if not module_name or not class_name:
+        raise ValueError(
+            f"Invalid runtime.adapter '{token}'. Expected format 'module.path:ClassName'."
+        )
+    return module_name, class_name
+
+
+def _normalize_event_name(event_name: str, aliases: dict[str, str]) -> str:
+    raw = str(event_name or "").strip()
+    if raw in aliases:
+        return aliases[raw]
+    token = raw.lower().replace("-", "_")
+    return aliases.get(token) or aliases.get(token.replace("_", "")) or token
+
+
+def _normalize_claude_payload(payload: dict[str, Any]) -> dict[str, Any]:
+    _normalize_tool_name(payload, candidate_keys=("tool_name", "tool", "toolName", "action"))
+    _normalize_session_id(payload)
+    if "stop_fields" not in payload and "cortex_stop" in payload:
+        payload["stop_fields"] = payload.get("cortex_stop")
+    return payload
+
+
+def _normalize_claude_stop_fields(message: str) -> tuple[dict[str, Any] | None, str]:
+    parsed, _, _ = parse_stop_fields_json(message)
+    passthrough = _strip_gemini_stop_markers(message)
+    if isinstance(parsed, dict):
+        stop_fields = {str(k): v for k, v in parsed.items()}
+        if passthrough and not stop_fields.get("summary"):
+            stop_fields["summary"] = passthrough
+        return stop_fields, passthrough
+    return None, passthrough or message.strip()
+
+
+_ADAPTER_PATH_ALIASES = {
+    "cortex.adapters.claude": "cortex.adapters",
+    "cortex.adapters.generic": "cortex.adapters",
+    "cortex.adapters.gemini": "cortex.adapters",
+    "cortex.adapters.openai": "cortex.adapters",
+}
+
+
+def _normalize_session_id(payload: dict[str, Any]) -> None:
+    raw_session_id = payload.get("session_id")
+    if isinstance(raw_session_id, str):
+        session_id = raw_session_id.strip()
+        if session_id:
+            payload["session_id"] = session_id
+            return
+    payload.pop("session_id", None)
+
+
+def _normalize_tool_name(payload: dict[str, Any], *, candidate_keys: tuple[str, ...]) -> None:
+    primary = payload.get("tool_name")
+    if isinstance(primary, str) and primary.strip():
+        payload["tool_name"] = primary.strip()
+        return
+    payload.pop("tool_name", None)
+    for key in candidate_keys:
+        val = payload.get(key)
+        if isinstance(val, str) and val.strip():
+            payload["tool_name"] = val.strip()
+            return
+
+
+def _normalize_gemini_status(payload: dict[str, Any]) -> None:
+    status = payload.get("status")
+    if isinstance(status, str) and status.strip():
+        payload["status"] = status.strip().lower()
+        return
+    tool_response = payload.get("tool_response")
+    if isinstance(tool_response, Mapping) and tool_response.get("error"):
+        payload["status"] = "error"
+        return
+    payload["status"] = "ok"
+
+
+def _normalize_gemini_stop_fields(prompt_response: str) -> tuple[dict[str, Any], str]:
+    parsed, marker_found, error = parse_stop_fields_json(prompt_response)
+    passthrough = _strip_gemini_stop_markers(prompt_response)
+
+    if isinstance(parsed, dict):
+        stop_fields = {str(k): v for k, v in parsed.items()}
+        if passthrough and not stop_fields.get("summary"):
+            stop_fields["summary"] = passthrough
+        return stop_fields, passthrough
+
+    stop_fields = _recover_partial_stop_fields(prompt_response)
+    if marker_found and error:
+        stop_fields["marker_parse_error"] = error
+    if passthrough:
+        stop_fields.setdefault("summary", passthrough)
+    elif prompt_response.strip():
+        stop_fields.setdefault("summary", prompt_response.strip())
+    return stop_fields, passthrough
+
+
+def _strip_gemini_stop_markers(text: str) -> str:
+    cleaned = text
+    fenced_patterns = (
+        r"```(?:stop-fields|stop_fields)\s*\{.*?\}\s*```",
+        r"```json\s*\{.*?\"challenge_coverage\".*?\}\s*```",
+    )
+    for pattern in fenced_patterns:
+        cleaned = re.sub(pattern, "", cleaned, flags=re.DOTALL | re.IGNORECASE)
+    marker = "STOP_FIELDS_JSON:"
+    marker_idx = cleaned.rfind(marker)
+    if marker_idx != -1:
+        cleaned = cleaned[:marker_idx]
+    return cleaned.strip()
+
+
+def _recover_partial_stop_fields(text: str) -> dict[str, Any]:
+    recovered: dict[str, Any] = {}
+
+    coverage: dict[str, bool] = {}
+    for key in ("null_inputs", "boundary_values", "error_handling", "graveyard_regression"):
+        match = re.search(rf'"{key}"\s*:\s*(true|false)', text, flags=re.IGNORECASE)
+        if match:
+            coverage[key] = match.group(1).lower() == "true"
+    if coverage:
+        recovered["challenge_coverage"] = coverage
+
+    truth_claims: dict[str, list[str]] = {}
+    for key in ("modified_files", "tests_ran"):
+        values = _recover_string_list(text, key)
+        if values:
+            truth_claims[key] = values
+    if truth_claims:
+        recovered["truth_claims"] = truth_claims
+
+    return recovered
+
+
+def _recover_string_list(text: str, key: str) -> list[str]:
+    match = re.search(rf'"{key}"\s*:\s*\[(.*?)\]', text, flags=re.DOTALL | re.IGNORECASE)
+    if not match:
+        return []
+    values: list[str] = []
+    seen: set[str] = set()
+    for token in re.findall(r'"((?:\\.|[^"\\])*)"', match.group(1)):
+        try:
+            value = str(json.loads(f'"{token}"'))
+        except json.JSONDecodeError:
+            value = token
+        cleaned = value.strip()
+        if not cleaned or cleaned in seen:
+            continue
+        seen.add(cleaned)
+        values.append(cleaned)
+    return values
+
+
+def _rewrite_legacy_trailer_markers(message: str) -> str:
+    return (
+        message.replace("CORTEX_STOP_JSON:", "STOP_FIELDS_JSON:")
+        .replace("```cortex-stop", "```stop-fields")
+        .replace("```cortex_stop", "```stop_fields")
+    )

cortex/blocklist.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+DEFAULT_BLOCKED_TOOLS: frozenset[str] = frozenset({
+    "vim",
+    "nvim",
+    "nano",
+    "emacs",
+    "vi",
+    "python_repl",
+    "ipython",
+    "node_repl",
+    "irb",
+    "gdb",
+    "lldb",
+    "pdb",
+    "less",
+    "more",
+    "man",
+    "ssh",
+    "docker_exec_interactive",
+    "kubectl_exec",
+})
+
+
+@dataclass(slots=True)
+class BlockVerdict:
+    blocked: bool
+    reason: str
+
+
+def evaluate_blocklist(
+    tool_name: object | None,
+    *,
+    enabled: bool = True,
+    blocked_tools: frozenset[str] = DEFAULT_BLOCKED_TOOLS,
+    allowed_tools: frozenset[str] = frozenset(),
+    fail_closed: bool = False,
+) -> BlockVerdict:
+    if not enabled:
+        return BlockVerdict(False, "blocklist_disabled")
+    normalized = "" if tool_name is None else str(tool_name).strip().lower()
+    normalized = normalized or "unknown"
+    if normalized in allowed_tools:
+        return BlockVerdict(False, "explicitly_allowed")
+    if normalized in blocked_tools:
+        return BlockVerdict(True, "tool_denied")
+    if fail_closed and normalized not in allowed_tools:
+        return BlockVerdict(True, "fail_closed")
+    return BlockVerdict(False, "not_in_denylist")

cortex/challenges.py

@@ -0,0 +1,210 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .genome import ChallengesConfig
+from .requirements import evaluate_evidence_reference
+from .store import SQLiteStore
+from .templates import BUILTIN_CHALLENGE_TEMPLATES
+from .utils import _as_string_list
+
+
+@dataclass(slots=True)
+class ChallengeCoverage:
+    category: str
+    covered: bool
+    evidence: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"category": self.category, "covered": self.covered, "evidence": self.evidence}
+
+
+@dataclass(slots=True)
+class ChallengeReport:
+    active_categories: list[str]
+    custom_paths: list[str]
+    results: list[ChallengeCoverage]
+    missing_categories: list[str]
+    unverified_categories: list[str]
+    uncheckable_categories: list[str]
+    diagnostics: list[dict[str, Any]]
+    config_warnings: list[str]
+    ok: bool
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "active_categories": self.active_categories,
+            "custom_paths": self.custom_paths,
+            "results": [r.to_dict() for r in self.results],
+            "missing_categories": self.missing_categories,
+            "unverified_categories": self.unverified_categories,
+            "uncheckable_categories": self.uncheckable_categories,
+            "diagnostics": self.diagnostics,
+            "config_warnings": self.config_warnings,
+            "ok": self.ok,
+        }
+
+
+class ChallengeEnforcer:
+    def __init__(self, store: SQLiteStore, config: ChallengesConfig) -> None:
+        self.store = store
+        self.config = config
+
+    def evaluate(
+        self,
+        session_id: str,
+        coverage_payload: Mapping[str, Any] | None = None,
+        *,
+        require_verifiable_coverage: bool = False,
+        root: Path | None = None,
+        witness: Mapping[str, list[str]] | None = None,
+    ) -> ChallengeReport:
+        coverage_payload = coverage_payload or {}
+        results: list[ChallengeCoverage] = []
+        missing: list[str] = []
+        unverified: list[str] = []
+        uncheckable: list[str] = []
+        diagnostics: list[dict[str, Any]] = []
+        config_warnings: list[str] = []
+        resolved_root = root.resolve() if root is not None else None
+
+        missing_builtin = [
+            name for name in BUILTIN_CHALLENGE_TEMPLATES if name not in self.config.active_categories
+        ]
+        if missing_builtin:
+            config_warnings.append(
+                "Built-in challenge categories missing from active set: " + ", ".join(missing_builtin)
+            )
+
+        for category in self.config.active_categories:
+            raw = coverage_payload.get(category)
+            covered, evidence = self._coerce_coverage(raw)
+            if require_verifiable_coverage and covered:
+                verification = self._verify_covered_category(
+                    evidence=evidence,
+                    root=resolved_root,
+                    witness=witness,
+                )
+                evidence["verification"] = verification
+                verification_status = str(verification.get("status") or "")
+                if verification_status != "verified":
+                    covered = False
+                    reason = str(verification.get("reason") or "missing verifiable evidence")
+                    if verification_status == "uncheckable":
+                        uncheckable.append(category)
+                    else:
+                        unverified.append(category)
+                    config_warnings.append(
+                        f"Challenge coverage '{category}' marked covered but evidence is {verification_status}: {reason}"
+                    )
+            if not covered:
+                missing.append(category)
+                diagnostics.append(
+                    self._coverage_diagnostic(
+                        category=category,
+                        raw=raw,
+                        evidence=evidence,
+                        require_verifiable_coverage=require_verifiable_coverage,
+                    )
+                )
+            result = ChallengeCoverage(category=category, covered=covered, evidence=evidence)
+            results.append(result)
+            self.store.record_challenge_result(session_id, category, covered, evidence)
+
+        ok = not missing if self.config.require_coverage else True
+        return ChallengeReport(
+            active_categories=list(self.config.active_categories),
+            custom_paths=list(self.config.custom_paths),
+            results=results,
+            missing_categories=missing,
+            unverified_categories=sorted(set(unverified)),
+            uncheckable_categories=sorted(set(uncheckable)),
+            diagnostics=diagnostics,
+            config_warnings=config_warnings,
+            ok=ok,
+        )
+
+    def missing_coverage_diagnostics(self) -> list[dict[str, Any]]:
+        return [
+            {"evidence_found": [], "evidence_expected": [f"challenge_coverage for: {', '.join(self.config.active_categories)}"], "gap_description": "No challenge_coverage was provided for the stop attempt.", "gap_characterization": "comprehension_gap", "distance_signal": "far"}
+        ]
+
+    def invalid_coverage_diagnostics(self, raw: Any) -> list[dict[str, Any]]:
+        return [
+            {"evidence_found": [f"challenge_coverage={type(raw).__name__}"], "evidence_expected": ["challenge_coverage object keyed by active challenge categories"], "gap_description": "Challenge coverage used an invalid payload shape.", "gap_characterization": "comprehension_gap", "distance_signal": "far"}
+        ]
+
+    @staticmethod
+    def _coerce_coverage(raw: Any) -> tuple[bool, dict[str, Any]]:
+        if isinstance(raw, bool):
+            return raw, {}
+        if isinstance(raw, Mapping):
+            covered = bool(raw.get("covered", False))
+            evidence = {str(k): v for k, v in raw.items() if str(k) != "covered"}
+            return covered, evidence
+        if raw is None:
+            return False, {}
+        return bool(raw), {"raw": raw}
+
+    @staticmethod
+    def _verify_covered_category(
+        *,
+        evidence: Mapping[str, Any],
+        root: Path | None,
+        witness: Mapping[str, list[str]] | None,
+    ) -> dict[str, Any]:
+        if root is None:
+            return {
+                "status": "uncheckable",
+                "reason": "verification root unavailable",
+                "checked_references": [],
+            }
+
+        references = _as_string_list(evidence.get("evidence"))
+        if not references:
+            return {
+                "status": "unverified",
+                "reason": "covered=true requires non-empty evidence list",
+                "checked_references": [],
+            }
+
+        checks = [evaluate_evidence_reference(ref, root=root, witness=witness) for ref in references]
+        if any(check.get("status") == "verified" for check in checks):
+            return {
+                "status": "verified",
+                "reason": "",
+                "checked_references": checks,
+            }
+        if any(check.get("status") == "uncheckable" for check in checks):
+            return {
+                "status": "uncheckable",
+                "reason": "no verifiable evidence reference was checkable",
+                "checked_references": checks,
+            }
+        return {
+            "status": "unverified",
+            "reason": "no evidence reference was verified",
+            "checked_references": checks,
+        }
+
+    @staticmethod
+    def _coverage_diagnostic(
+        *,
+        category: str,
+        raw: Any,
+        evidence: Mapping[str, Any],
+        require_verifiable_coverage: bool,
+    ) -> dict[str, Any]:
+        verification = evidence.get("verification") if isinstance(evidence, Mapping) else None
+        if raw is None:
+            return {"evidence_found": [], "evidence_expected": [f"challenge_coverage.{category}=true"], "gap_description": f"Challenge category '{category}' was not addressed in stop coverage.", "gap_characterization": "comprehension_gap", "distance_signal": "far"}
+
+        evidence_refs = _as_string_list(evidence.get("evidence")) if isinstance(evidence, Mapping) else []
+        if require_verifiable_coverage and isinstance(verification, Mapping):
+            status = str(verification.get("status") or "unverified")
+            return {"evidence_found": evidence_refs or [f"verification_status={status}"], "evidence_expected": [f"verifiable evidence for challenge '{category}'"], "gap_description": f"Challenge category '{category}' was claimed but not verifiably supported.", "gap_characterization": "execution_gap", "distance_signal": "moderate" if evidence_refs else "far"}
+
+        return {"evidence_found": ["covered=false"], "evidence_expected": [f"challenge_coverage.{category}=true"], "gap_description": f"Challenge category '{category}' remains uncovered.", "gap_characterization": "comprehension_gap", "distance_signal": "moderate"}

cortex/cli.py

@@ -0,0 +1,7 @@
+import sys
+from importlib import import_module
+from types import ModuleType
+
+_IMPL = import_module("cortex_ops_cli.main")
+sys.modules[__name__].__class__ = type("_ShimModule", (ModuleType,), {"__getattr__": lambda self, name: getattr(_IMPL, name), "__setattr__": lambda self, name, value: (setattr(_IMPL, name, value), ModuleType.__setattr__(self, name, value))[1]})
+if __name__ == "__main__": raise SystemExit(_IMPL.main())  # noqa: E701