cortex-loop 0.1.0a1__py3-none-any.whl

cortex/core.py

@@ -0,0 +1,601 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from .adapters import EventAdapter, load_adapter
+from .challenges import ChallengeEnforcer
+from .core_helpers import (
+    extract_required_requirement_ids,
+    foundation_warnings_from_snapshot,
+    session_foundation_snapshot,
+    session_changed_files_since_baseline,
+    session_git_snapshot,
+    session_metadata,
+    session_required_requirement_ids,
+    session_witness_context,
+)
+from .executive import (
+    get_base_executive_function,
+    get_identity_preamble,
+    get_learned_executive_function,
+    record_stop_failure_event,
+    run_decay,
+)
+from .foundation import FoundationAnalyzer
+from .genome import CortexGenome, load_genome
+from .graveyard import Graveyard, explainability_warnings
+from .invariants import InvariantRunner
+from .blocklist import DEFAULT_BLOCKED_TOOLS, evaluate_blocklist
+from .retry import compute_retry_verdict
+from .stop_contract import resolve_stop_contract
+from .stop_runtime import StopPathRunner
+from .store import SQLiteStore
+from .utils import _as_string_list
+
+
+@dataclass(slots=True)
+class KernelContext:
+    root: Path
+    genome_path: Path
+    db_path: Path
+    genome: CortexGenome
+    store: SQLiteStore
+
+
+class CortexKernel:
+    """Hook-driven orchestration kernel for Cortex subsystems."""
+
+    def __init__(
+        self,
+        root: str | Path | None = None,
+        *,
+        config_path: str | Path | None = None,
+        db_path: str | Path | None = None,
+        adapter_name: str | None = None,
+        adapter: EventAdapter | None = None,
+    ) -> None:
+        if adapter_name is not None:
+            raise ValueError(
+                "adapter_name is no longer supported. Configure [runtime].adapter in cortex.toml."
+            )
+        repo_root = Path(root or os.getcwd()).resolve()
+        genome_path = Path(config_path).resolve() if config_path else repo_root / "cortex.toml"
+        store = SQLiteStore(Path(db_path).resolve() if db_path else repo_root / ".cortex" / "cortex.db")
+        store.initialize()
+        genome = load_genome(genome_path)
+        self.ctx = KernelContext(
+            root=repo_root,
+            genome_path=genome_path,
+            db_path=store.db_path,
+            genome=genome,
+            store=store,
+        )
+        self.foundation = FoundationAnalyzer(repo_root, genome.foundation)
+        self.graveyard = Graveyard(store, genome.graveyard)
+        self.challenges = ChallengeEnforcer(store, genome.challenges)
+        self.invariants = InvariantRunner(
+            repo_root,
+            store,
+            genome.invariants,
+            genome.hooks,
+            trust_profile=genome.project.trust_profile,
+        )
+        self.adapter = adapter or load_adapter(genome.runtime.adapter)
+        self.stop_path = StopPathRunner(
+            root=repo_root,
+            store=store,
+            genome=genome,
+            challenges=self.challenges,
+            invariants=self.invariants,
+            graveyard=self.graveyard,
+            session_metadata_loader=lambda active_store, active_session_id: session_metadata(
+                active_store, active_session_id
+            ),
+            session_git_snapshotter=lambda active_root: session_git_snapshot(active_root),
+            session_changed_files_since_baseline_fn=(
+                lambda **kwargs: session_changed_files_since_baseline(**kwargs)
+            ),
+            session_required_requirement_ids_loader=(
+                lambda active_store, active_session_id: session_required_requirement_ids(
+                    active_store, active_session_id
+                )
+            ),
+            session_witness_context_loader=(
+                lambda active_store, active_session_id: session_witness_context(
+                    active_store, active_session_id
+                )
+            ),
+        )
+        self._known_sessions: set[str] = set()
+
+    def on_session_start(self, payload: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        payload = self.adapter.normalize("session_start", payload).payload
+        session_id = self._session_id(payload)
+        part_a_full, _part_b = get_base_executive_function()
+        executive_cfg = self.ctx.genome.executive
+        part_a = part_a_full if executive_cfg.part_a_mode != "once_per_project" else ""
+        identity_preamble = ""
+        required_requirement_ids = extract_required_requirement_ids(payload)
+        session_meta: dict[str, Any] = {"hook": "SessionStart"}
+        session_counter = self.ctx.store.allocate_session_counter(session_id)
+        session_meta["session_counter"] = session_counter
+        if required_requirement_ids:
+            session_meta["required_requirement_ids"] = required_requirement_ids
+        session_meta["git_snapshot"] = session_git_snapshot(self.ctx.root)
+        self._record_event(session_id, "SessionStart", payload)
+
+        learned_patterns = ""
+        if executive_cfg.enabled:
+            if executive_cfg.inject_identity_preamble:
+                identity_preamble = get_identity_preamble()
+            pruned = run_decay(
+                self.ctx.store,
+                halflife_sessions=executive_cfg.halflife_sessions,
+                threshold=executive_cfg.decay_threshold,
+                min_hold_sessions=executive_cfg.min_hold_sessions,
+            )
+            session_meta["executive_decay_pruned"] = pruned
+            learned_patterns = get_learned_executive_function(
+                self.ctx.store,
+                halflife_sessions=executive_cfg.halflife_sessions,
+                inject_threshold=executive_cfg.inject_threshold,
+                decay_threshold=executive_cfg.decay_threshold,
+                max_entries=executive_cfg.max_entries,
+                max_tokens=executive_cfg.max_tokens,
+                min_hold_sessions=executive_cfg.min_hold_sessions,
+            )
+
+        foundation_report = self.foundation.analyze()
+        session_meta["foundation"] = {
+            "warnings": list(foundation_report.warnings),
+            "findings": [finding.to_dict() for finding in foundation_report.findings],
+        }
+        self.ctx.store.upsert_session_start(
+            session_id=session_id,
+            status="running",
+            genome_path=self.ctx.genome.source_path,
+            metadata=session_meta,
+        )
+        self._known_sessions.add(session_id)
+        task_summary = str(payload.get("task") or payload.get("objective") or "")
+        target_files = _as_string_list(payload.get("target_files"))
+        graveyard_matches = [m.to_dict() for m in self.graveyard.find_similar(task_summary, target_files)]
+        repomap_summary = self._session_start_repomap(session_id=session_id, payload=payload)
+
+        warnings = list(foundation_report.warnings)
+        if self.ctx.genome.parse_error:
+            warnings.append(f"Config parse error in {self.ctx.genome.source_path}: {self.ctx.genome.parse_error}")
+        if self.ctx.genome.load_warnings:
+            warnings.extend(f"Config warning: {warning}" for warning in self.ctx.genome.load_warnings)
+        if graveyard_matches:
+            warnings.append(f"Found {len(graveyard_matches)} graveyard match(es) relevant to this session.")
+            warnings.extend(explainability_warnings(graveyard_matches))
+        if repomap_summary and repomap_summary.get("warning"):
+            warnings.append(str(repomap_summary["warning"]))
+        graveyard_context = _graveyard_context_block(graveyard_matches, self.ctx.genome.graveyard)
+        if executive_cfg.part_a_mode == "once_per_project":
+            part_a = part_a_full if self.ctx.store.claim_meta_once("executive.part_a_injected") else ""
+        context_blocks: list[str] = []
+        if identity_preamble:
+            context_blocks.append(identity_preamble)
+        if part_a:
+            context_blocks.append(part_a)
+        if learned_patterns:
+            context_blocks.append(learned_patterns)
+        if graveyard_context:
+            context_blocks.append(graveyard_context)
+
+        return self._response(
+            hook="SessionStart",
+            session_id=session_id,
+            warnings=warnings,
+            foundation=foundation_report.to_dict(),
+            graveyard_matches=graveyard_matches,
+            repomap=repomap_summary,
+            required_requirement_ids=required_requirement_ids,
+            executive_context={
+                "identity_preamble": identity_preamble,
+                "part_a": part_a,
+                "learned": learned_patterns,
+            },
+            context_blocks=context_blocks,
+        )
+
+    def on_pre_tool_use(self, payload: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        payload = self.adapter.normalize("pre_tool_use", payload).payload
+        session_id = self._session_id(payload)
+        tool_name = str(payload.get("tool_name") or "").strip() or None
+        self._record_event(
+            session_id,
+            "PreToolUse",
+            payload,
+            tool_name=tool_name,
+            status=str(payload.get("status")) if payload.get("status") is not None else None,
+        )
+
+        warnings: list[str] = []
+        proceed = True
+
+        # --- Blocklist gate ---------------------------------------------------
+        bl_cfg = self.ctx.genome.blocklist
+        if bl_cfg.enabled:
+            cfg_blocked = frozenset(t.strip().lower() for t in bl_cfg.blocked_tools if t.strip())
+            effective_blocked = (cfg_blocked | DEFAULT_BLOCKED_TOOLS) if cfg_blocked else DEFAULT_BLOCKED_TOOLS
+            effective_allowed = frozenset(t.strip().lower() for t in bl_cfg.allowed_tools if t.strip())
+            verdict = evaluate_blocklist(
+                tool_name,
+                blocked_tools=effective_blocked,
+                allowed_tools=effective_allowed,
+                fail_closed=bl_cfg.fail_closed,
+            )
+            if verdict.blocked:
+                proceed = False
+                warnings.append(
+                    f"Tool '{tool_name or 'unknown'}' blocked by denylist ({verdict.reason})."
+                )
+
+        target_files = _as_string_list(payload.get("target_files")) + _as_string_list(payload.get("planned_files"))
+        if target_files:
+            warnings.extend(self._foundation_warnings(session_id=session_id, target_files=target_files))
+
+        return self._response(
+            hook="PreToolUse",
+            session_id=session_id,
+            warnings=warnings,
+            proceed=proceed,
+        )
+
+    def on_session_marker(self, payload: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        payload = self.adapter.normalize("session_marker", payload).payload
+        label = str(payload.get("label") or "").strip()
+        if not label:
+            raise ValueError("session_marker requires non-empty 'label'.")
+        session_id = str(payload.get("session_id") or "").strip()
+        if not session_id:
+            raise ValueError("session_marker requires session_id.")
+        self._record_event(session_id, "SessionMarker", {"label": label})
+        return self._response(hook="SessionMarker", session_id=session_id, warnings=[], label=label)
+
+    def on_post_tool_use(self, payload: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        payload = self.adapter.normalize("post_tool_use", payload).payload
+        session_id = self._session_id(payload)
+        tool_name = str(payload.get("tool_name") or "").strip() or None
+        self._record_event(
+            session_id,
+            "PostToolUse",
+            payload,
+            tool_name=tool_name,
+            status=str(payload.get("status")) if payload.get("status") is not None else None,
+        )
+
+        warnings: list[str] = []
+        retry_verdict = None
+        if str(payload.get("status", "")).lower() in {"error", "failed", "fail"}:
+            summary = str(payload.get("error") or payload.get("message") or "")
+            target_files = _as_string_list(payload.get("target_files"))
+            matches = self.graveyard.find_similar(summary, target_files, max_matches=3)
+            if matches:
+                warnings.append(
+                    f"Tool failure resembles {len(matches)} graveyard entry/entries; review before retrying."
+                )
+                warnings.extend(explainability_warnings([m.to_dict() for m in matches]))
+
+            if self.ctx.genome.retry.enabled:
+                retry_verdict = compute_retry_verdict(
+                    store=self.ctx.store,
+                    session_id=session_id,
+                    payload=payload,
+                    max_retries=self.ctx.genome.retry.max_retries,
+                )
+                if retry_verdict:
+                    self._record_event(
+                        session_id,
+                        "RetryConsume",
+                        {
+                            "should_retry": retry_verdict.should_retry,
+                            "reason": retry_verdict.reason,
+                            "failure_class": retry_verdict.failure_class,
+                            "status": str(payload.get("status") or ""),
+                            "tool_name": tool_name,
+                            "budget_remaining": retry_verdict.budget_remaining,
+                            "budget_exhausted": retry_verdict.budget_exhausted,
+                            "decision_code": retry_verdict.decision_code,
+                            "failure_signature": retry_verdict.failure_signature,
+                        },
+                        tool_name=tool_name,
+                        status="consumed" if retry_verdict.should_retry else "rejected",
+                    )
+
+        retry_info: dict[str, Any] | None = None
+        if retry_verdict is not None:
+            retry_info = {
+                "should_retry": retry_verdict.should_retry,
+                "hard_stop": retry_verdict.hard_stop,
+                "failure_class": retry_verdict.failure_class,
+                "reason": retry_verdict.reason,
+                "budget_remaining": retry_verdict.budget_remaining,
+                "budget_exhausted": retry_verdict.budget_exhausted,
+                "decision_code": retry_verdict.decision_code,
+            }
+            if retry_verdict.hard_stop:
+                warnings.append(f"Hard stop: non-retryable failure ({retry_verdict.reason}).")
+            elif retry_verdict.decision_code == "no_delta":
+                warnings.append("Retry suppressed: no delta detected for repeated failure signature.")
+            elif retry_verdict.decision_code == "retry_contention":
+                warnings.append("Retry contention detected; retry slot was not acquired. Re-evaluate and retry after state settles.")
+            elif retry_verdict.decision_code == "reason_budget_exhausted":
+                warnings.append("Reason-specific retry budget exhausted; no further retries allowed for this failure reason.")
+            elif retry_verdict.budget_exhausted:
+                warnings.append("Retry budget exhausted; no further retries allowed.")
+
+        proceed = not (retry_verdict is not None and retry_verdict.hard_stop)
+
+        return self._response(
+            hook="PostToolUse",
+            session_id=session_id,
+            warnings=warnings,
+            proceed=proceed,
+            retry=retry_info,
+        )
+
+    def on_stop(self, payload: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        payload = self.adapter.normalize("stop", payload).payload
+        session_id = self._session_id(payload)
+        stop_contract = resolve_stop_contract(
+            payload,
+            allow_message_fallback=self.ctx.genome.hooks.allow_message_stop_fallback,
+            require_structured_stop_payload=self.ctx.genome.hooks.require_structured_stop_payload,
+        )
+        self._record_event(
+            session_id,
+            "Stop",
+            payload,
+            capture_git_snapshot=True,
+        )
+        stop_outcome = self.stop_path.run(
+            session_id=session_id,
+            payload=payload,
+            stop_contract=stop_contract,
+        )
+        requirement_audit = stop_outcome.requirement_audit
+        truth_claims = stop_outcome.truth_claims
+        challenge_report = stop_outcome.challenge_report
+        invariant_report = stop_outcome.invariant_report
+        requirement_audit_gap = requirement_audit.gap
+        truth_claims_gap = truth_claims.gap
+        requirements_gate_gap = requirement_audit_gap or truth_claims_gap
+        executive_record, executive_signature = (None, None)
+        if self.ctx.genome.executive.enabled:
+            executive_record, executive_signature = record_stop_failure_event(
+                self.ctx.store,
+                session_id=session_id,
+                structured_stop_violation=stop_outcome.structured_stop_violation,
+                challenge_coverage_missing=stop_outcome.missing_challenge_coverage,
+                challenge_report=None if challenge_report is None else challenge_report.to_dict(),
+                requirements_gate_gap=requirements_gate_gap,
+                requirement_audit_report=requirement_audit.report,
+                truth_claims_report=truth_claims.report,
+                invariant_report=None if invariant_report is None else invariant_report.to_dict(),
+                signature_claim=lambda sig: self.ctx.store.claim_executive_stop_signature(session_id, sig),
+            )
+
+        self.ctx.store.close_session(
+            session_id=session_id,
+            status=stop_outcome.session_status,
+            metadata=self.stop_path.close_session_metadata(
+                outcome=stop_outcome,
+                stop_contract=stop_contract,
+                executive_signature=executive_signature,
+                executive_record=executive_record,
+            ),
+        )
+
+        return self._response(
+            hook="Stop",
+            session_id=session_id,
+            warnings=stop_outcome.warnings,
+            **self.stop_path.response_payload(
+                outcome=stop_outcome,
+                stop_contract=stop_contract,
+            ),
+        )
+
+    def dispatch(self, event_name: str, payload: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        event_name = self.adapter.normalize(event_name, None).name
+        if event_name == "session_start":
+            return self.on_session_start(payload)
+        if event_name == "session_marker":
+            return self.on_session_marker(payload)
+        if event_name == "pre_tool_use":
+            return self.on_pre_tool_use(payload)
+        if event_name == "post_tool_use":
+            return self.on_post_tool_use(payload)
+        if event_name == "stop":
+            return self.on_stop(payload)
+        raise ValueError(f"Unknown hook event: {event_name}")
+
+    def _record_event(
+        self,
+        session_id: str,
+        hook: str,
+        payload: Mapping[str, Any],
+        *,
+        tool_name: str | None = None,
+        status: str | None = None,
+        capture_git_snapshot: bool = True,
+    ) -> None:
+        self._ensure_session_started(session_id=session_id, hook=hook, capture_git_snapshot=capture_git_snapshot)
+        self.ctx.store.record_event(
+            session_id=session_id,
+            hook=hook,
+            payload=dict(payload),
+            tool_name=tool_name,
+            status=status,
+        )
+
+    def _response(self, *, hook: str, session_id: str, warnings: list[str], **extra: Any) -> dict[str, Any]:
+        response = {
+            "ok": True,
+            "hook": hook,
+            "session_id": session_id,
+            "mode": self.ctx.genome.hooks.mode,
+            "warnings": warnings,
+            **extra,
+        }
+        if not self.ctx.genome.hooks.minimal_response:
+            response["config"] = {
+                "genome_path": self._response_path(self.ctx.genome_path),
+                "db_path": self._response_path(self.ctx.db_path),
+            }
+        return response
+
+    def _ensure_session_started(self, *, session_id: str, hook: str, capture_git_snapshot: bool = True) -> None:
+        if session_id in self._known_sessions:
+            return
+        metadata: dict[str, Any] = {"hook": hook, "auto_started": hook != "SessionStart"}
+        if not session_metadata(self.ctx.store, session_id) and hook != "SessionStart" and capture_git_snapshot:
+            metadata["git_snapshot"] = session_git_snapshot(self.ctx.root)
+        self.ctx.store.ensure_session_start(
+            session_id=session_id,
+            status="running",
+            genome_path=self.ctx.genome.source_path,
+            metadata=metadata,
+        )
+        self._known_sessions.add(session_id)
+
+    def _session_start_repomap(
+        self,
+        *,
+        session_id: str,
+        payload: Mapping[str, Any],
+    ) -> dict[str, Any] | None:
+        repomap_cfg = self.ctx.genome.repomap
+        if not (repomap_cfg.enabled and repomap_cfg.run_on_session_start):
+            return None
+
+        focus_files = _as_string_list(payload.get("target_files"))
+        try:
+            from .repomap import run_repomap
+
+            result = run_repomap(
+                root=self.ctx.root,
+                repomap_config=repomap_cfg,
+                focus_files=focus_files or None,
+                session_id=session_id,
+                timeout_ms=repomap_cfg.session_start_timeout_ms,
+            )
+        except Exception as exc:  # noqa: BLE001
+            summary = {
+                "ok": False,
+                "artifact_path": None,
+                "method": "none",
+                "scope": list(repomap_cfg.watch_paths),
+                "stats": {
+                    "files_parsed": 0,
+                    "symbols_found": 0,
+                    "graph_edges": 0,
+                    "byte_count": 0,
+                },
+                "top_ranked_files": [],
+                "error": {"code": "internal_error", "message": str(exc)},
+                "warning": "Repo-map generation failed during session start (non-blocking).",
+            }
+            self._record_event(
+                session_id,
+                "RepoMap",
+                {
+                    "trigger": "SessionStart",
+                    "ok": False,
+                    "error": summary["error"],
+                    "scope": summary["scope"],
+                },
+                status="error",
+            )
+            return summary
+
+        artifact = result.artifact
+        top_ranked_files = [entry.path for entry in artifact.ranking[:5]]
+        summary = {
+            "ok": bool(result.ok),
+            "artifact_path": result.artifact_path,
+            "method": str(artifact.provenance.get("method", "none")),
+            "scope": list(artifact.provenance.get("scope", [])),
+            "stats": dict(artifact.stats),
+            "top_ranked_files": top_ranked_files,
+        }
+        event_payload: dict[str, Any] = {
+            "trigger": "SessionStart",
+            "ok": bool(result.ok),
+            "artifact_path": result.artifact_path,
+            "method": summary["method"],
+            "scope": summary["scope"],
+            "stats": summary["stats"],
+            "top_ranked_files": top_ranked_files,
+        }
+        if not result.ok and artifact.error:
+            error = {
+                "code": str(artifact.error.get("code", "internal_error")),
+                "message": str(artifact.error.get("message", "Repo-map generation failed")),
+            }
+            summary["error"] = error
+            summary["warning"] = f"Repo-map warning: {error['message']}"
+            event_payload["error"] = error
+
+        self._record_event(
+            session_id,
+            "RepoMap",
+            event_payload,
+            status="ok" if result.ok else "error",
+        )
+        return summary
+
+    def _response_path(self, path: Path) -> str:
+        resolved = path.resolve()
+        return str(resolved.relative_to(self.ctx.root)) if resolved.is_relative_to(self.ctx.root) else str(resolved)
+
+    @staticmethod
+    def _session_id(payload: Mapping[str, Any]) -> str: return (payload.get("session_id") or "").strip() if isinstance(payload.get("session_id"), str) and str(payload.get("session_id")).strip() else f"sess-{uuid4().hex[:12]}"
+
+    def _foundation_warnings(self, *, session_id: str, target_files: list[str]) -> list[str]:
+        return foundation_warnings_from_snapshot(foundation=self.foundation, snapshot=session_foundation_snapshot(self.ctx.store, session_id), target_files=target_files)
+
+def _graveyard_context_block(matches: list[dict[str, Any]], config: Any) -> str:
+    if not matches:
+        return ""
+    max_matches = max(1, int(getattr(config, "context_max_matches", 2)))
+    summary_chars = max(40, int(getattr(config, "context_summary_chars", 140)))
+    reason_chars = max(40, int(getattr(config, "context_reason_chars", 200)))
+    token_budget = max(50, int(getattr(config, "context_max_tokens", 300)))
+
+    lines = ["## Graveyard context"]
+    used_tokens = _approx_tokens(lines[0])
+    for idx, match in enumerate(matches[:max_matches], start=1):
+        summary = _truncate_context_text(str(match.get("summary") or "").strip(), summary_chars)
+        reason = _truncate_context_text(str(match.get("reason") or "").strip(), reason_chars)
+        files = _as_string_list(match.get("files"))
+        entry_lines = [f"{idx}. {summary}" if summary else f"{idx}. Prior failure pattern"]
+        if reason:
+            entry_lines.append(f"Reason: {reason}")
+        if files:
+            entry_lines.append("Files: " + ", ".join(files[:5]))
+        entry_tokens = _approx_tokens("\n".join(entry_lines))
+        if used_tokens + entry_tokens > token_budget:
+            break
+        lines.extend(entry_lines)
+        used_tokens += entry_tokens
+    return "\n".join(lines).strip() if len(lines) > 1 else ""
+
+
+def _truncate_context_text(text: str, max_chars: int) -> str:
+    if len(text) <= max_chars:
+        return text
+    return text[: max(1, max_chars - 3)].rstrip() + "..."
+
+
+def _approx_tokens(text: str) -> int:
+    return max(1, len(text) // 4)