engineering-platform 2.2.0__py3-none-any.whl

engineering_platform/assets/dashboard_status_store.mjs

@@ -0,0 +1,41 @@
+export function normalizeDashboardStatus(status, fallback) {
+  return status && typeof status === "object" && !Array.isArray(status)
+    ? status
+    : fallback;
+}
+
+export function normalizeDashboardSnapshot(snapshot) {
+  return snapshot && typeof snapshot === "object" && !Array.isArray(snapshot)
+    ? snapshot
+    : {};
+}
+
+export function createDashboardStatusStore({ fallback, render }) {
+  if (typeof render !== "function")
+    throw new TypeError("A dashboard status renderer is required.");
+
+  let latestSnapshotSource = null, latestSnapshotRevision = -1;
+  const store = {
+    status: fallback,
+    snapshot: {},
+    update(status, snapshot = {}) {
+      const nextStatus = normalizeDashboardStatus(status, fallback);
+      const nextSnapshot = normalizeDashboardSnapshot(snapshot);
+      const source = typeof nextSnapshot.snapshot_source === "string" ? nextSnapshot.snapshot_source : null;
+      const revision = Number.isSafeInteger(nextSnapshot.snapshot_revision) && nextSnapshot.snapshot_revision >= 0
+        ? nextSnapshot.snapshot_revision
+        : null;
+      if (source && revision !== null) {
+        if (source === latestSnapshotSource && revision < latestSnapshotRevision)
+          return { status: store.status, snapshot: store.snapshot };
+        if (source !== latestSnapshotSource) latestSnapshotSource = source;
+        latestSnapshotRevision = revision;
+      }
+      store.status = nextStatus;
+      store.snapshot = nextSnapshot;
+      render(store.status, store.snapshot);
+      return { status: store.status, snapshot: store.snapshot };
+    },
+  };
+  return store;
+}

engineering_platform/assets/operations-console/manifest.webmanifest

@@ -0,0 +1,11 @@
+{
+  "name": "EP Operations",
+  "short_name": "EP Operations",
+  "display": "standalone",
+  "background_color": "#0a6b9d",
+  "theme_color": "#0a6b9d",
+  "icons": [
+    {"src": "/assets/operations-console/icon-dark.png", "sizes": "1254x1254", "type": "image/png", "purpose": "any"},
+    {"src": "/assets/operations-console/icon-light.png", "sizes": "1254x1254", "type": "image/png", "purpose": "any"}
+  ]
+}

engineering_platform/capability_preflight.py

@@ -0,0 +1,285 @@
+"""Fail-closed Level 3 capability admission for Engineering Inbox work.
+
+This module evaluates only declared transaction requirements against the local
+Execution Host contract.  It never claims an Inbox item, allocates a run or
+touches a target repository.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+import json
+import os
+from pathlib import Path
+import re
+import tempfile
+from time import monotonic
+
+from .platform_version import (
+    EngineeringPlatformCompatibilityError,
+    EngineeringPlatformManifest,
+    RunnerCompatibility,
+    _semver,
+)
+from .drift_diagnostics import evidence_for_checks, guidance, persist as persist_drift_evidence
+from .provider_readiness import failures as provider_readiness_failures
+from .central_database import capacity_reserve_from_environment
+from .codex_capacity import read_remaining_percent
+from .resources import package_path
+
+RECOVERABILITY = frozenset(
+    {
+        "RETRYABLE",
+        "RETRYABLE_AFTER_HOST_REPAIR",
+        "REQUIRES_NEW_PROMPT",
+        "REQUIRES_OPERATOR_DECISION",
+        "NON_RETRYABLE",
+    }
+)
+FAILURE_ORIGINS = frozenset(
+    {"HOST", "WORKSPACE", "CAPABILITY", "VALIDATION", "ENGINEERING", "GOVERNANCE"}
+)
+
+
+@dataclass(frozen=True)
+class CapabilityCheck:
+    identifier: str
+    outcome: str
+    reason: str
+    recovery: str
+
+
+@dataclass(frozen=True)
+class CapabilityPreflightResult:
+    outcome: str
+    timestamp: str
+    duration_ms: int
+    checks: tuple[CapabilityCheck, ...]
+    recoverability: str
+    failure_origin: str | None
+    recommendation: str
+    drift_evidence: tuple[dict[str, str], ...] = ()
+    resume_guidance: dict[str, object] | None = None
+
+    def payload(self, run_id: str | None = None) -> dict[str, object]:
+        value = asdict(self)
+        value["checks"] = [asdict(check) for check in self.checks]
+        value["run_id"] = run_id
+        return value
+
+
+def _check(identifier: str, passed: bool, reason: str, recovery: str) -> CapabilityCheck:
+    return CapabilityCheck(identifier, "PASS" if passed else "FAIL", reason, recovery)
+
+
+def _value(prompt: str, field: str) -> str | None:
+    match = re.search(rf"(?mi)^\s*{re.escape(field)}\s*:\s*([^\n]+)$", prompt)
+    return match.group(1).strip() if match else None
+
+
+def _requirements(prompt: str) -> dict[str, str]:
+    """Read a bounded, provider-neutral declaration from the transaction."""
+    aliases = {
+        "Execution Host Version": "platform_version",
+        "Runner Version": "runner_version",
+        "Configuration Schema": "configuration_schema",
+        "Engineering Database Schema": "storage_schema",
+        "Checkpoint Format": "checkpoint_format",
+        "Memory Format": "memory_format",
+        "Report Format": "report_format",
+        "Execution Mode": "execution_mode",
+        "Required Runtime Components": "runtime_components",
+        "Required Provider Support": "provider_support",
+        "Required Capabilities": "capabilities",
+    }
+    return {key: value for field, key in aliases.items() if (value := _value(prompt, field))}
+
+
+def _persist(root: Path, result: CapabilityPreflightResult, run_id: str | None) -> None:
+    directory = root / ".engineering" / "status"
+    if not directory.is_dir():
+        return
+    temporary: str | None = None
+    try:
+        descriptor, temporary = tempfile.mkstemp(prefix=".capability-preflight-", dir=directory)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(
+                json.dumps(result.payload(run_id), separators=(",", ":"), sort_keys=True) + "\n"
+            )
+        os.replace(temporary, directory / "capability_preflight.json")
+    except OSError:
+        if temporary:
+            Path(temporary).unlink(missing_ok=True)
+
+
+def execute(root: Path, prompt: str, *, run_id: str | None = None) -> CapabilityPreflightResult:
+    """Evaluate declared requirements before claim; absent declarations are compatible."""
+    started, checks = monotonic(), []
+    requirements = _requirements(prompt)
+    mode = requirements.get("execution_mode", "MANAGED").strip().upper()
+    required_providers = provider_readiness_failures(root, require_github=mode != "GENESIS")
+    checks.append(
+        _check(
+            "provider_readiness",
+            not required_providers,
+            "Required provider sessions are ready." if not required_providers else "Required provider sessions need attention: " + ", ".join(required_providers) + ".",
+            "Use the Engineering dashboard provider notification to install or sign in, then retry admission.",
+        )
+    )
+    reserve_percent = capacity_reserve_from_environment()
+    if reserve_percent:
+        remaining = read_remaining_percent()
+        capacity_ready = remaining is not None and remaining >= reserve_percent
+        checks.append(
+            _check(
+                "codex_capacity_reserve",
+                capacity_ready,
+                (
+                    f"Codex has {remaining:.0f}% remaining; the configured reserve is {reserve_percent}%."
+                    if remaining is not None
+                    else "Codex capacity could not be verified for the configured admission reserve."
+                ),
+                "Wait for Codex capacity to recover or lower the reserve in Available AI capacity before retrying admission.",
+            )
+        )
+    try:
+        manifest = EngineeringPlatformManifest.load(
+            package_path("ENGINEERING_PLATFORM_VERSION.json")
+        )
+        runner = RunnerCompatibility()
+    except EngineeringPlatformCompatibilityError as error:
+        checks.append(
+            _check("host_contract", False, str(error), "Repair the Execution Host contract.")
+        )
+        manifest = None
+        runner = None
+    if manifest and runner:
+        versions = (
+            (
+                "platform_version",
+                "execution_host_version",
+                manifest.platform_version,
+                runner.platform_version,
+            ),
+            ("runner_version", "runner_version", manifest.runner_version, runner.runner_version),
+        )
+        for requirement, identifier, available, actual in versions:
+            required = requirements.get(requirement)
+            passed = not required or _semver(actual, identifier) >= _semver(required, requirement)
+            checks.append(
+                _check(
+                    identifier,
+                    passed,
+                    f"Required {required or 'none'}; available {available}.",
+                    "Upgrade the Execution Host or submit a compatible prompt.",
+                )
+            )
+        formats = (
+            ("checkpoint_format", manifest.checkpoint_format, runner.checkpoint_formats),
+            ("memory_format", manifest.memory_format, runner.memory_formats),
+            ("report_format", manifest.report_format, runner.report_formats),
+            ("storage_schema", manifest.storage_schema, runner.storage_schemas),
+        )
+        for requirement, available, supported in formats:
+            required = (
+                int(requirements[requirement])
+                if requirements.get(requirement, "").isdigit()
+                else available
+            )
+            checks.append(
+                _check(
+                    requirement,
+                    required in supported,
+                    f"Required {required}; supported {sorted(supported)}.",
+                    "Upgrade the Execution Host or use a supported format.",
+                )
+            )
+        configuration_schema = (
+            int(requirements["configuration_schema"])
+            if requirements.get("configuration_schema", "").isdigit()
+            else 1
+        )
+        checks.append(
+            _check(
+                "configuration_schema",
+                configuration_schema == 1,
+                f"Required {configuration_schema}; supported [1].",
+                "Upgrade the Execution Host or use configuration schema 1.",
+            )
+        )
+        mode = requirements.get("execution_mode", "MANAGED").upper()
+        checks.append(
+            _check(
+                "execution_mode",
+                mode in {"MANAGED", "GENESIS"},
+                f"Execution mode {mode} is supported."
+                if mode in {"MANAGED", "GENESIS"}
+                else f"Execution mode {mode} is unsupported.",
+                "Use Managed or Genesis execution mode.",
+            )
+        )
+        for requirement, identifier, available in (
+            ("runtime_components", "runtime_components", {"codex", "python", "git"}),
+            ("provider_support", "provider_support", {"launchd"}),
+            (
+                "capabilities",
+                "required_capabilities",
+                {
+                    "workspace_authorization",
+                    "host_preflight",
+                    "workspace_preflight",
+                    "capability_preflight",
+                },
+            ),
+        ):
+            requested = {
+                item.strip().casefold()
+                for item in requirements.get(requirement, "").split(",")
+                if item.strip()
+            }
+            missing = requested - available
+            checks.append(
+                _check(
+                    identifier,
+                    not missing,
+                    "All declared requirements are available."
+                    if not missing
+                    else f"Unsupported requirements: {', '.join(sorted(missing))}.",
+                    "Install or configure the required host capability before retrying.",
+                )
+            )
+    failed = any(check.outcome == "FAIL" for check in checks)
+    drift_evidence = persist_drift_evidence(root, evidence_for_checks(
+        checks, stage="Capability Preflight", repository=str(root.resolve())
+    ))
+    result = CapabilityPreflightResult(
+        "FAIL" if failed else "PASS",
+        datetime.now(timezone.utc).isoformat(),
+        round((monotonic() - started) * 1000),
+        tuple(checks),
+        "RETRYABLE_AFTER_HOST_REPAIR" if failed else "RETRYABLE",
+        "CAPABILITY" if failed else None,
+        "Repair or upgrade the Execution Host before resubmitting."
+        if failed
+        else "Capability admission passed.",
+        drift_evidence,
+        guidance(drift_evidence),
+    )
+    _persist(root, result, run_id)
+    return result
+
+
+def latest(root: Path) -> dict[str, object]:
+    try:
+        payload = json.loads(
+            (root / ".engineering/status/capability_preflight.json").read_text(encoding="utf-8")
+        )
+    except (OSError, json.JSONDecodeError):
+        return {}
+    if not isinstance(payload, dict):
+        return {}
+    return {key: payload[key] for key in (
+        "outcome", "timestamp", "duration_ms", "checks", "recoverability",
+        "failure_origin", "recommendation", "drift_evidence", "resume_guidance", "run_id",
+    ) if key in payload}

engineering_platform/capability_review.py

@@ -0,0 +1,261 @@
+"""Deterministic, read-only capability reviewer selection for the Execution Host."""
+
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+import json
+from pathlib import Path
+from typing import Callable, Protocol
+
+from .agent_state import redact_diagnostic
+from .provider_context import ProviderRole, project_context
+from .provider_context_scope import ContextScope, POLICY_ID, provider_instruction
+from .reviewer_evidence import ReviewerEvidence
+
+
+REVIEWER_ORDER = (
+    "apple_platform",
+    "windows_platform",
+    "home_assistant_integration",
+    "esphome_firmware",
+    "pi_renderer",
+    "universal_receiver",
+    "website",
+    "api",
+    "repository_governance",
+    "validation",
+    "documentation",
+    "finalization",
+)
+REVIEWER_LABELS = {
+    "apple_platform": "Apple Platform Reviewer",
+    "windows_platform": "Windows Platform Reviewer",
+    "home_assistant_integration": "Home Assistant Integration Reviewer",
+    "esphome_firmware": "ESPHome Firmware Reviewer",
+    "pi_renderer": "Pi Renderer Reviewer",
+    "universal_receiver": "Universal Receiver Reviewer",
+    "website": "Website Reviewer",
+    "api": "API Reviewer",
+    "repository_governance": "Repository Governance Reviewer",
+    "validation": "Validation Reviewer",
+    "documentation": "Documentation Reviewer",
+    "finalization": "Finalization Reviewer",
+}
+PRODUCT_MATCHERS = {
+    "apple_platform": (("apps/apple/", "engineering-platform-app", "swiftui", "watchos", "macos", "ios"), "Apple platform capability"),
+    "windows_platform": (("apps/windows/", "engineering-platform-windows", "maui", "windows packaging"), "Windows platform capability"),
+    "home_assistant_integration": (("custom_components/engineering_platform", "home assistant", "config flow", "options flow", "coordinator", "entity model"), "Home Assistant integration capability"),
+    "esphome_firmware": (("esphome", "engineering-platform-esp32", "firmware yaml", ".yaml"), "ESPHome firmware capability"),
+    "pi_renderer": (("engineering-platform-pi", "pi renderer", "raspberry pi", "display lifecycle"), "Pi renderer capability"),
+    "universal_receiver": (("universal receiver", "vibecast", "browser receiver", "receiver transport"), "Universal Receiver capability"),
+    "website": (("engineering-platform-website", "website", "static site", "product messaging"), "Website capability"),
+    "api": (("engineering-platform-api", "rest api", "api contract", "api documentation"), "API capability"),
+}
+
+
+@dataclass(frozen=True)
+class ReviewerSelection:
+    reviewer: str
+    selected_because: str
+    confidence: float
+    capability: str = "engineering"
+
+
+@dataclass(frozen=True)
+class ReviewerResult:
+    reviewer: str
+    contribution: str
+    recommendations: tuple[str, ...] = ()
+    failed: bool = False
+    usage: dict[str, object] = field(default_factory=dict)
+    runtime_metadata: dict[str, object] = field(default_factory=dict)
+    churn: dict[str, object] = field(default_factory=dict)
+    duration_seconds: float | None = None
+    usage_snapshots: tuple[dict[str, int], ...] = ()
+
+
+class ReviewerClient(Protocol):
+    def review(
+        self,
+        root: Path,
+        selection: ReviewerSelection,
+        objective: str,
+        evidence: ReviewerEvidence | None = None,
+    ) -> ReviewerResult: ...
+
+
+def select_reviewers(objective: str, prompt_path: Path, transaction_kind: str, memory: object) -> tuple[ReviewerSelection, ...]:
+    """Select only registered reviewers from objective, lifecycle and safe memory evidence."""
+    text = f"{prompt_path.name} {objective}".lower()
+    selected: dict[str, str] = {}
+    for reviewer, (markers, reason) in PRODUCT_MATCHERS.items():
+        if any(marker in text for marker in markers):
+            selected[reviewer] = reason
+    if any(token in text for token in ("governance", "repository", "roadmap", "policy", "bootstrap")):
+        selected["repository_governance"] = "repository-governance objective"
+    if any(token in text for token in ("test", "ruff", "bandit", "assurance", "validation", "failure")):
+        selected["validation"] = "validation-related objective"
+    if prompt_path.suffix.lower() == ".md" or any(token in text for token in ("document", "wording", "readme", "backlog")):
+        selected["documentation"] = "documentation-oriented objective"
+    if transaction_kind == "FINALIZATION" or "finalization" in text:
+        selected["finalization"] = "Finalization lifecycle evidence"
+    history = _reviewer_memory(memory)
+    result: list[ReviewerSelection] = []
+    for reviewer in REVIEWER_ORDER:
+        reason = selected.get(reviewer)
+        if reason is None:
+            continue
+        confidence = min(1.0, 0.5 + history.get(reviewer, 0.0))
+        capability = reviewer if reviewer in PRODUCT_MATCHERS else "engineering"
+        result.append(ReviewerSelection(reviewer, reason, confidence, capability))
+    return tuple(result)
+
+
+ReviewerProgressCallback = Callable[[ReviewerSelection, str, ReviewerResult | None], None]
+
+
+def run_reviews(
+    root: Path,
+    selections: tuple[ReviewerSelection, ...],
+    objective: str,
+    client: ReviewerClient | None,
+    progress: ReviewerProgressCallback | None = None,
+    evidence: ReviewerEvidence | None = None,
+) -> tuple[ReviewerResult, ...]:
+    """Run independent read-only reviews in parallel; any failure remains advisory."""
+    if not selections:
+        return ()
+    if client is None:
+        results = tuple(ReviewerResult(item.reviewer, "Reviewer client unavailable; primary review continues.", failed=True) for item in selections)
+        if progress:
+            for selection, result in zip(selections, results, strict=True):
+                progress(selection, "failed", result)
+        return results
+
+    def invoke(selection: ReviewerSelection) -> ReviewerResult:
+        if progress:
+            progress(selection, "started", None)
+        try:
+            result = client.review(root, selection, objective, evidence)
+            if result.reviewer != selection.reviewer:
+                result = ReviewerResult(selection.reviewer, "Reviewer identity mismatch; primary review continues.", failed=True)
+            else:
+                result = ReviewerResult(
+                selection.reviewer,
+                redact_diagnostic(result.contribution, limit=240),
+                tuple(redact_diagnostic(value, limit=240) for value in result.recommendations[:3]),
+                result.failed,
+                result.usage,
+                result.runtime_metadata,
+                result.churn,
+                result.duration_seconds,
+            )
+        except Exception:  # Reviewer failure is advisory and cannot block the transaction.
+            result = ReviewerResult(selection.reviewer, "Reviewer failed; primary review continues.", failed=True)
+        if progress:
+            progress(selection, "failed" if result.failed else "completed", result)
+        return result
+
+    with ThreadPoolExecutor(max_workers=len(selections)) as executor:
+        completed = {item.reviewer: executor.submit(invoke, item) for item in selections}
+        return tuple(completed[item.reviewer].result() for item in selections)
+
+
+def reconciled_recommendations(results: tuple[ReviewerResult, ...]) -> tuple[str, ...]:
+    """Deduplicate safe advisory recommendations for the primary agent prompt."""
+    accepted: list[str] = []
+    for result in results:
+        if result.failed:
+            continue
+        for recommendation in result.recommendations:
+            if recommendation and recommendation not in accepted:
+                accepted.append(recommendation)
+    return tuple(accepted[:8])
+
+
+def records_for_storage(selections: tuple[ReviewerSelection, ...], results: tuple[ReviewerResult, ...]) -> tuple[dict[str, object], ...]:
+    by_reviewer = {result.reviewer: result for result in results}
+    records: list[dict[str, object]] = []
+    for selection in selections:
+        result = by_reviewer.get(selection.reviewer, ReviewerResult(selection.reviewer, "No result.", failed=True))
+        records.append({
+            "reviewer": selection.reviewer,
+            "capability": selection.capability,
+            "selected_because": selection.selected_because,
+            "confidence": selection.confidence,
+            "contribution": result.contribution,
+            "accepted_recommendations": len(result.recommendations) if not result.failed else 0,
+            "rejected_recommendations": 0,
+            "failed": result.failed,
+            "codex_commands_executed": _command_count(result.churn),
+        })
+    return tuple(records)
+
+
+def _command_count(churn: object) -> int:
+    """Return the safe, per-review command total without sharing agent state."""
+    if not isinstance(churn, dict):
+        return 0
+    value = churn.get("tool_loop_operations", 0)
+    return value if isinstance(value, int) and not isinstance(value, bool) and value >= 0 else 0
+
+
+def _reviewer_memory(memory: object) -> dict[str, float]:
+    if not isinstance(memory, dict):
+        return {}
+    result: dict[str, float] = {}
+    for entry in memory.get("reviewers", []):
+        if isinstance(entry, dict) and entry.get("reviewer") in REVIEWER_ORDER:
+            confidence = entry.get("future_confidence")
+            if isinstance(confidence, (int, float)) and 0.0 <= confidence <= 1.0:
+                result[str(entry["reviewer"])] = float(confidence)
+    return result
+
+
+def reviewer_prompt(
+    selection: ReviewerSelection,
+    objective: str,
+    evidence: ReviewerEvidence | None = None,
+) -> str:
+    """Build the bounded read-only reviewer instruction without lifecycle authority."""
+    projection = project_context(ProviderRole.SPECIALIST_REVIEW, objective)
+    prompt: dict[str, object] = {
+        "reviewer": REVIEWER_LABELS[selection.reviewer],
+        "capability": selection.capability,
+        "selected_because": selection.selected_because,
+        "objective": projection.text,
+        "context_projection": {
+            "role": projection.role.value,
+            "budget_version": projection.budget_version,
+            "source_item_count": projection.source_item_count,
+            "omitted_low_priority_count": projection.omitted_low_priority_count,
+        },
+        "provider_context_scope": {
+            "policy": POLICY_ID,
+            "initial_scope": ContextScope.NORMAL.value,
+            "instruction": provider_instruction(ContextScope.NORMAL),
+        },
+        "authority": "Read-only inspection and recommendations only. Do not edit, commit, push, merge, create pull requests, finalize, or change lifecycle state.",
+        "scope": "Analyse only the declared capability. Cross-capability analysis requires objective repository evidence.",
+    }
+    if evidence is not None:
+        prompt["run_scoped_repository_evidence"] = evidence.to_dict()
+        prompt["evidence_instructions"] = (
+            "These are host-observed facts for this exact Run ID, collected after "
+            "synchronization and before this reviewer wave. Reuse them for ordinary "
+            "repository-state questions; do not rediscover branch, HEAD, worktree, "
+            "repository identity, or main ancestry with Git/GitHub. They are facts, "
+            "not conclusions. Retrieve only narrower additional evidence that your "
+            "capability review genuinely requires. This snapshot expires at any "
+            "repository mutation, validation, PR/merge, finalization, or cleanup boundary."
+        )
+    prompt["invocation_read_reuse"] = (
+        "Within this one reviewer invocation, reuse already inspected immutable file "
+        "content for factual inspection rather than accidentally rereading it. "
+        "Do not share content, conclusions, or reasoning with another reviewer or "
+        "Run ID. Reread after an edit, generated-artifact refresh, repository "
+        "change, validation, PR/merge, finalization, cleanup, or whenever freshness "
+        "is uncertain. Deliberate verification reads remain required."
+    )
+    return json.dumps(prompt, sort_keys=True)