@trac3r/oh-my-god 2.2.11

package/runtime/budget_envelopes.py

@@ -0,0 +1,398 @@
+"""Multi-dimensional budget envelopes — CPU, memory, wall time, tokens, and network.
+
+Tracks per-run and per-worker resource usage against configurable limits.
+Persists envelope state to `.omg/state/budget-envelopes/<run_id>.json`.
+Feeds into session health, worker watchdogs, and governed tool decisions.
+
+Governance actions:
+  - warn:    log only, no execution impact
+  - reflect: pause and report to supervisor
+  - block:   terminate / reject further work
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from hooks.security_validators import sanitize_run_id
+
+
+# ═══════════════════════════════════════════════════════════
+# Dataclasses
+# ═══════════════════════════════════════════════════════════
+
+
+@dataclass
+class BudgetEnvelope:
+    """Declared resource limits for a run or worker."""
+
+    run_id: str
+    cpu_seconds_limit: float = 0.0
+    memory_mb_limit: float = 0.0
+    wall_time_seconds_limit: float = 0.0
+    token_limit: int = 0
+    network_bytes_limit: int = 0
+
+
+@dataclass
+class BudgetEnvelopeState:
+    """Current resource usage tracking for a run or worker."""
+
+    run_id: str
+    cpu_seconds_used: float = 0.0
+    memory_mb_peak: float = 0.0
+    wall_time_seconds_elapsed: float = 0.0
+    tokens_used: int = 0
+    network_bytes_used: int = 0
+    started_at: str = ""
+    updated_at: str = ""
+    status: str = "active"  # "active" or "closed"
+
+
+@dataclass
+class EnvelopeCheckResult:
+    """Result of checking a run against its envelope limits."""
+
+    status: str  # "ok", "warn", "breach"
+    breached_dimensions: list[str] = field(default_factory=list)
+    governance_action: str = "warn"  # "warn", "reflect", "block"
+    reason: str = ""
+
+
+# ═══════════════════════════════════════════════════════════
+# Constants
+# ═══════════════════════════════════════════════════════════
+
+_GOVERNANCE_ACTIONS = frozenset({"warn", "reflect", "block"})
+
+# Warn at 80%, block at 100% by default
+_DEFAULT_WARN_RATIO = 0.80
+_DEFAULT_BLOCK_RATIO = 1.00
+
+_ENVELOPE_STATE_REL = Path(".omg") / "state" / "budget-envelopes"
+
+
+# ═══════════════════════════════════════════════════════════
+# Manager
+# ═══════════════════════════════════════════════════════════
+
+
+class BudgetEnvelopeManager:
+    """Create, track, and enforce multi-dimensional budget envelopes.
+
+    Envelopes are persisted as JSON to `.omg/state/budget-envelopes/<run_id>.json`.
+    """
+
+    def __init__(self, project_dir: str | None = None):
+        if project_dir:
+            self.project_dir = Path(project_dir)
+        else:
+            self.project_dir = Path(os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd()))
+
+    # --- Paths ---
+
+    def _envelope_dir(self) -> Path:
+        return self.project_dir / _ENVELOPE_STATE_REL
+
+    def _envelope_path(self, run_id: str) -> Path:
+        return self._envelope_dir() / f"{sanitize_run_id(run_id)}.json"
+
+    # --- CRUD ---
+
+    def create_envelope(
+        self,
+        run_id: str,
+        *,
+        cpu_seconds_limit: float = 0.0,
+        memory_mb_limit: float = 0.0,
+        wall_time_seconds_limit: float = 0.0,
+        token_limit: int = 0,
+        network_bytes_limit: int = 0,
+    ) -> dict[str, Any]:
+        """Create and persist a new budget envelope for *run_id*.
+
+        Returns the full persisted state dict.
+        """
+        now = _now_iso()
+        envelope = BudgetEnvelope(
+            run_id=run_id,
+            cpu_seconds_limit=cpu_seconds_limit,
+            memory_mb_limit=memory_mb_limit,
+            wall_time_seconds_limit=wall_time_seconds_limit,
+            token_limit=token_limit,
+            network_bytes_limit=network_bytes_limit,
+        )
+        state = BudgetEnvelopeState(
+            run_id=run_id,
+            started_at=now,
+            updated_at=now,
+        )
+        payload: dict[str, Any] = {
+            "schema": "BudgetEnvelopeState",
+            "schema_version": "1.0.0",
+            "status": "active",
+            "envelope": asdict(envelope),
+            "usage": asdict(state),
+            "checks": [],
+        }
+        _write_atomic_json(self._envelope_path(run_id), payload)
+        return payload
+
+    def record_usage(
+        self,
+        run_id: str,
+        *,
+        cpu_seconds: float = 0.0,
+        memory_mb: float = 0.0,
+        wall_time_seconds: float = 0.0,
+        tokens: int = 0,
+        network_bytes: int = 0,
+    ) -> dict[str, Any]:
+        """Increment usage counters for *run_id*.
+
+        Memory is tracked as peak (max), all others are additive.
+        Returns the updated state dict.
+        """
+        payload = self._read_state(run_id)
+        if not payload:
+            # Auto-create a zero-limit envelope (uncapped) so usage is still tracked
+            payload = self.create_envelope(run_id)
+
+        usage = payload.get("usage", {})
+        usage["cpu_seconds_used"] = _to_float(usage.get("cpu_seconds_used"), 0.0) + cpu_seconds
+        usage["memory_mb_peak"] = max(
+            _to_float(usage.get("memory_mb_peak"), 0.0),
+            memory_mb,
+        )
+        usage["wall_time_seconds_elapsed"] = (
+            _to_float(usage.get("wall_time_seconds_elapsed"), 0.0) + wall_time_seconds
+        )
+        usage["tokens_used"] = _to_int(usage.get("tokens_used"), 0) + tokens
+        usage["network_bytes_used"] = _to_int(usage.get("network_bytes_used"), 0) + network_bytes
+        usage["updated_at"] = _now_iso()
+        payload["usage"] = usage
+
+        _write_atomic_json(self._envelope_path(run_id), payload)
+        return payload
+
+    def check_envelope(self, run_id: str) -> EnvelopeCheckResult:
+        """Compare current usage against envelope limits.
+
+        Returns an ``EnvelopeCheckResult`` with status, breached dimensions, and
+        the appropriate governance action.
+
+        Governance escalation logic:
+          - No limit set (0) → dimension is uncapped, never breaches.
+          - Usage >= 100% of limit → status=breach, action=block.
+          - Usage >= 80% of limit → status=warn, action=warn (first time) or reflect (repeated).
+          - Otherwise → status=ok, action=warn (no-op).
+        """
+        payload = self._read_state(run_id)
+        if not payload:
+            return EnvelopeCheckResult(status="ok", reason="no envelope found")
+        if payload.get("status", "active") == "closed":
+            return EnvelopeCheckResult(status="ok", reason="envelope closed")
+
+        envelope = payload.get("envelope", {})
+        usage = payload.get("usage", {})
+        checks_history: list[dict[str, Any]] = payload.get("checks", [])
+
+        breached: list[str] = []
+        warned: list[str] = []
+
+        _DIMS: list[tuple[str, str, str]] = [
+            ("cpu_seconds_limit", "cpu_seconds_used", "cpu"),
+            ("memory_mb_limit", "memory_mb_peak", "memory"),
+            ("wall_time_seconds_limit", "wall_time_seconds_elapsed", "wall_time"),
+            ("token_limit", "tokens_used", "tokens"),
+            ("network_bytes_limit", "network_bytes_used", "network"),
+        ]
+
+        for limit_key, used_key, dim_name in _DIMS:
+            limit_val = _to_float(envelope.get(limit_key), 0.0)
+            if limit_val <= 0:
+                continue  # uncapped
+            used_val = _to_float(usage.get(used_key), 0.0)
+            ratio = used_val / limit_val
+
+            if ratio >= _DEFAULT_BLOCK_RATIO:
+                breached.append(dim_name)
+            elif ratio >= _DEFAULT_WARN_RATIO:
+                warned.append(dim_name)
+
+        # Determine governance action
+        if breached:
+            status = "breach"
+            governance_action = "block"
+            reason = f"envelope breached on: {', '.join(breached)}"
+        elif warned:
+            # Escalate to reflect if we warned before on the same dimensions
+            prior_warned = set()
+            for chk in checks_history:
+                if chk.get("status") == "warn":
+                    prior_warned.update(chk.get("breached_dimensions", []))
+            repeat_warns = set(warned) & prior_warned
+            if repeat_warns:
+                status = "warn"
+                governance_action = "reflect"
+                reason = f"repeated warning on: {', '.join(sorted(repeat_warns))}"
+            else:
+                status = "warn"
+                governance_action = "warn"
+                reason = f"approaching limits on: {', '.join(warned)}"
+        else:
+            status = "ok"
+            governance_action = "warn"  # no-op sentinel
+            reason = "all dimensions within limits"
+
+        result = EnvelopeCheckResult(
+            status=status,
+            breached_dimensions=breached or warned,
+            governance_action=governance_action,
+            reason=reason,
+        )
+
+        # Persist check result in history
+        check_record = {
+            "checked_at": _now_iso(),
+            "status": result.status,
+            "breached_dimensions": list(result.breached_dimensions),
+            "governance_action": result.governance_action,
+            "reason": result.reason,
+        }
+        checks_history.append(check_record)
+        if len(checks_history) > 50:
+            checks_history = checks_history[-50:]
+        payload["checks"] = checks_history
+        _write_atomic_json(self._envelope_path(run_id), payload)
+
+        return result
+
+    def close_envelope(self, run_id: str, reason: str) -> None:
+        payload = self._read_state(run_id)
+        if not payload:
+            return
+        payload["status"] = "closed"
+        payload["closed_at"] = _now_iso()
+        payload["close_reason"] = reason
+        _write_atomic_json(self._envelope_path(run_id), payload)
+
+    def list_envelopes(self) -> list[dict[str, Any]]:
+        env_dir = self._envelope_dir()
+        if not env_dir.exists():
+            return []
+        result: list[dict[str, Any]] = []
+        for path in sorted(env_dir.glob("*.json")):
+            if path.name.endswith(".tmp"):
+                continue
+            payload = _read_json(path)
+            if not payload:
+                continue
+            result.append({
+                "run_id": payload.get("usage", {}).get("run_id", path.stem),
+                "status": payload.get("status", "active"),
+                "envelope": payload.get("envelope", {}),
+                "usage": payload.get("usage", {}),
+                "checks_count": len(payload.get("checks", [])),
+            })
+        return result
+
+    def prune_check_history(self, run_id: str, max_entries: int = 50) -> None:
+        payload = self._read_state(run_id)
+        if not payload:
+            return
+        checks = payload.get("checks", [])
+        if len(checks) > max_entries:
+            payload["checks"] = checks[-max_entries:]
+            _write_atomic_json(self._envelope_path(run_id), payload)
+
+    def get_envelope_state(self, run_id: str) -> dict[str, Any] | None:
+        payload = self._read_state(run_id)
+        return payload if payload else None
+
+    def get_envelope_pressure(self, run_id: str) -> dict[str, float]:
+        payload = self._read_state(run_id)
+        if not payload:
+            return {}
+        if payload.get("status", "active") == "closed":
+            return {}
+
+        envelope = payload.get("envelope", {})
+        usage = payload.get("usage", {})
+        pressure: dict[str, float] = {}
+
+        _DIMS: list[tuple[str, str, str]] = [
+            ("cpu_seconds_limit", "cpu_seconds_used", "cpu"),
+            ("memory_mb_limit", "memory_mb_peak", "memory"),
+            ("wall_time_seconds_limit", "wall_time_seconds_elapsed", "wall_time"),
+            ("token_limit", "tokens_used", "tokens"),
+            ("network_bytes_limit", "network_bytes_used", "network"),
+        ]
+
+        for limit_key, used_key, dim_name in _DIMS:
+            limit_val = _to_float(envelope.get(limit_key), 0.0)
+            if limit_val <= 0:
+                continue
+            used_val = _to_float(usage.get(used_key), 0.0)
+            pressure[dim_name] = round(used_val / limit_val, 4)
+
+        return pressure
+
+    # --- Internal ---
+
+    def _read_state(self, run_id: str) -> dict[str, Any]:
+        return _read_json(self._envelope_path(run_id))
+
+
+# ═══════════════════════════════════════════════════════════
+# Helpers
+# ═══════════════════════════════════════════════════════════
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _write_atomic_json(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = path.with_name(f"{path.name}.tmp")
+    tmp_path.write_text(
+        json.dumps(payload, indent=2, ensure_ascii=True) + "\n",
+        encoding="utf-8",
+    )
+    os.replace(tmp_path, path)
+
+
+def _read_json(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def _to_float(value: Any, default: float) -> float:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _to_int(value: Any, default: int) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def get_budget_envelope_manager(project_dir: str | None = None) -> BudgetEnvelopeManager:
+    """Factory for BudgetEnvelopeManager instances."""
+    return BudgetEnvelopeManager(project_dir)

package/runtime/business_workflow.py

@@ -0,0 +1,234 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+DEFAULT_WORKFLOW_PATH: tuple[str, ...] = (
+    "plan",
+    "implement",
+    "qa",
+    "simulate",
+    "final_test",
+    "production",
+)
+
+_STAGE_ALIASES = {
+    "plan": "plan",
+    "planning": "plan",
+    "implement": "implement",
+    "implementation": "implement",
+    "build": "implement",
+    "qa": "qa",
+    "quality": "qa",
+    "quality_assurance": "qa",
+    "test": "final_test",
+    "testing": "final_test",
+    "final_test": "final_test",
+    "final-testing": "final_test",
+    "simulate": "simulate",
+    "simulation": "simulate",
+    "prod": "production",
+    "production": "production",
+    "deploy": "production",
+}
+
+
+def _as_string_list(value: Any) -> list[str]:
+    if isinstance(value, str):
+        text = value.strip()
+        return [text] if text else []
+    if isinstance(value, Iterable):
+        items: list[str] = []
+        for raw in value:
+            if isinstance(raw, str):
+                text = raw.strip()
+                if text:
+                    items.append(text)
+        return items
+    return []
+
+
+def _resolve_workflow_path(idea: dict[str, Any]) -> list[str]:
+    raw_path = idea.get("workflow") or idea.get("path") or idea.get("delivery_path") or idea.get("workflow_path")
+    requested = _as_string_list(raw_path)
+    resolved: list[str] = []
+    for stage in requested:
+        key = _STAGE_ALIASES.get(stage.strip().lower())
+        if key and key not in resolved:
+            resolved.append(key)
+    if not resolved:
+        return list(DEFAULT_WORKFLOW_PATH)
+    for required in DEFAULT_WORKFLOW_PATH:
+        if required not in resolved:
+            resolved.append(required)
+    return resolved
+
+
+def build_business_task_plan(idea: dict[str, Any]) -> dict[str, Any]:
+    goal = str(idea.get("goal", "")).strip() or "unspecified-goal"
+    constraints = _as_string_list(idea.get("constraints", []))
+    acceptance = _as_string_list(idea.get("acceptance", []))
+    user_instructions = _as_string_list(idea.get("user_instructions", []))
+    workflow_path = _resolve_workflow_path(idea)
+
+    # Plan Council extensions
+    assumptions = _as_string_list(idea.get("assumptions", []))
+    objections = _as_string_list(idea.get("objections", []) or idea.get("dissent", []))
+    rollback_plan = _as_string_list(idea.get("rollback_plan", []))
+    verification_commands = _as_string_list(idea.get("verification_commands", []))
+    evidence_requirements = _as_string_list(idea.get("evidence_requirements", []))
+    falsifiability = _as_string_list(idea.get("falsifiability", []))
+
+    tasks: list[dict[str, Any]] = []
+    task_id = 1
+
+    if user_instructions:
+        for instruction in user_instructions:
+            tasks.append(
+                {
+                    "id": f"T{task_id}",
+                    "stage": "plan",
+                    "title": "Capture user instruction",
+                    "detail": instruction,
+                    "source": "user_instructions",
+                }
+            )
+            task_id += 1
+
+    for item in constraints:
+        tasks.append(
+            {
+                "id": f"T{task_id}",
+                "stage": "plan",
+                "title": "Capture delivery constraint",
+                "detail": item,
+                "source": "constraints",
+            }
+        )
+        task_id += 1
+
+    if "implement" in workflow_path:
+        tasks.append(
+            {
+                "id": f"T{task_id}",
+                "stage": "implement",
+                "title": "Implement scoped changes",
+                "detail": "Apply changes that satisfy user instructions and follow repository patterns.",
+                "source": "workflow",
+            }
+        )
+        task_id += 1
+
+    if "qa" in workflow_path:
+        tasks.append(
+            {
+                "id": f"T{task_id}",
+                "stage": "qa",
+                "title": "Run QA checks",
+                "detail": "Validate behavior against constraints and acceptance criteria.",
+                "source": "workflow",
+            }
+        )
+        task_id += 1
+
+    if "simulate" in workflow_path:
+        tasks.append(
+            {
+                "id": f"T{task_id}",
+                "stage": "simulate",
+                "title": "Simulate delivery scenarios",
+                "detail": "Exercise expected paths and edge cases before final testing.",
+                "source": "workflow",
+            }
+        )
+        task_id += 1
+
+    for item in acceptance:
+        tasks.append(
+            {
+                "id": f"T{task_id}",
+                "stage": "final_test",
+                "title": "Validate acceptance criterion",
+                "detail": item,
+                "source": "acceptance",
+            }
+        )
+        task_id += 1
+
+    if "production" in workflow_path:
+        tasks.append(
+            {
+                "id": f"T{task_id}",
+                "stage": "production",
+                "title": "Prepare production handoff",
+                "detail": "Confirm release readiness, residual risks, and deployment checks.",
+                "source": "workflow",
+            }
+        )
+
+    stage_summaries = []
+    for stage in workflow_path:
+        stage_tasks = [task for task in tasks if task["stage"] == stage]
+        stage_summaries.append(
+            {
+                "stage": stage,
+                "task_count": len(stage_tasks),
+                "tasks": stage_tasks,
+            }
+        )
+
+    return {
+        "goal": goal,
+        "requested_path": _as_string_list(
+            idea.get("workflow") or idea.get("path") or idea.get("delivery_path") or idea.get("workflow_path")
+        ),
+        "resolved_path": workflow_path,
+        "constraints": constraints,
+        "acceptance": acceptance,
+        "user_instructions": user_instructions,
+        "assumptions": assumptions,
+        "objections": objections,
+        "rollback_plan": rollback_plan,
+        "verification_commands": verification_commands,
+        "evidence_requirements": evidence_requirements,
+        "falsifiability": falsifiability,
+        "stages": stage_summaries,
+        "task_count": len(tasks),
+    }
+
+
+def build_business_workflow_result(
+    *,
+    idea: dict[str, Any],
+    plan: dict[str, Any],
+    execution: dict[str, Any],
+    verification: dict[str, Any],
+) -> dict[str, Any]:
+    plan_payload = build_business_task_plan(idea)
+    checks_value = verification.get("checks") if isinstance(verification, dict) else None
+    checks = checks_value if isinstance(checks_value, list) else []
+    checks_ok = bool(checks) and all(isinstance(check, dict) and check.get("passed") is True for check in checks)
+
+    stage_status = {
+        "plan": "completed" if plan.get("status") == "planned" else "failed",
+        "implement": "completed" if execution.get("status") == "executed" else "failed",
+        "qa": "completed" if checks_ok else "failed",
+        "simulate": "completed" if checks_ok else "failed",
+        "final_test": "completed" if checks_ok else "failed",
+        "production": "ready" if checks_ok else "blocked",
+    }
+
+    return {
+        "goal": plan_payload["goal"],
+        "workflow_path": plan_payload["resolved_path"],
+        "requested_workflow_path": plan_payload["requested_path"],
+        "task_plan": plan_payload,
+        "stage_status": [
+            {
+                "stage": stage,
+                "status": stage_status.get(stage, "pending"),
+            }
+            for stage in plan_payload["resolved_path"]
+        ],
+        "ready_for_production": checks_ok,
+    }

package/runtime/canonical_surface.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Final
+
+from runtime.evidence_requirements import EVIDENCE_REQUIREMENTS_BY_PROFILE, normalize_profile
+
+CANONICAL_PARITY_HOSTS: Final[list[str]] = ["claude", "codex", "gemini", "kimi"]
+COMPATIBILITY_ONLY_HOSTS: Final[list[str]] = ["opencode"]
+
+DOMAIN_DEFAULTS: Final[dict[str, tuple[str, ...]]] = {
+    "preflight_domain_packs": ("robotics", "vision", "algorithms", "health"),
+    "all_domain_packs": ("robotics", "vision", "algorithms", "health", "cybersecurity"),
+}
+
+def _release_evidence_profile_labels() -> dict[str, str]:
+    """Generate release labels synchronized with the normalized profile registry."""
+    return {
+        normalize_profile(profile).replace("-", "_"): profile
+        for profile in EVIDENCE_REQUIREMENTS_BY_PROFILE
+    }
+
+
+RELEASE_SURFACE_LABELS: Final[dict[str, dict[str, str]]] = {
+    "evidence_profiles": {
+        **_release_evidence_profile_labels(),
+    },
+    "routes": {
+        "teams": "teams",
+        "security_check": "security-check",
+        "api_twin": "api-twin",
+        "crazy": "crazy",
+    },
+}
+
+
+def get_canonical_hosts() -> list[str]:
+    return list(CANONICAL_PARITY_HOSTS)
+
+
+def get_compat_hosts() -> list[str]:
+    return list(COMPATIBILITY_ONLY_HOSTS)
+
+
+def get_all_supported_hosts() -> list[str]:
+    return [*CANONICAL_PARITY_HOSTS, *COMPATIBILITY_ONLY_HOSTS]
+
+
+def is_canonical_parity_host(host: str) -> bool:
+    return str(host).strip().lower() in CANONICAL_PARITY_HOSTS
+
+
+def is_compat_only_host(host: str) -> bool:
+    return str(host).strip().lower() in COMPATIBILITY_ONLY_HOSTS