engineering-platform 2.2.0__py3-none-any.whl

engineering_platform/execution_activity.py

@@ -0,0 +1,218 @@
+"""Versioned execution-activity evidence with explicit scope boundaries.
+
+Only aggregate counters and Git-derived path metadata are retained.  Raw
+commands, prompts, output, tokens, and workspace paths are deliberately out
+of scope for this projection.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import json
+from pathlib import Path
+
+from .storage import EngineeringStorageError, open_storage
+
+
+EXECUTION_ACTIVITY_SUMMARY_VERSION = 1
+CODEX_COMMAND_DEFINITION = (
+    "One persisted Codex CLI provider invocation. It is not a shell command, "
+    "tool call, prompt, token count, or GitHub API request."
+)
+
+
+def _git(root: Path, *args: str) -> str | None:
+    """Use a small, read-only Git command without retaining its output."""
+    from .providers import GitProvider
+    try:
+        result = GitProvider().execute(root, "git", *args)
+    except OSError:
+        return None
+    return result.stdout.strip() if result.returncode == 0 else None
+
+
+def live_worktree_snapshot(root: Path) -> dict[str, object]:
+    """Return a volatile current-uncommitted-state snapshot for active runs."""
+    status = _git(root, "status", "--porcelain", "--untracked-files=all")
+    counts = {"modified": 0, "added": 0, "deleted": 0}
+    if status is None:
+        availability = "UNAVAILABLE"
+    else:
+        availability = "AVAILABLE"
+        for row in status.splitlines():
+            code = row[:2]
+            if "D" in code:
+                counts["deleted"] += 1
+            elif "A" in code or "?" in code:
+                counts["added"] += 1
+            elif code.strip():
+                counts["modified"] += 1
+    return {
+        "kind": "LIVE_WORKTREE_SNAPSHOT",
+        "volatile": True,
+        "observed_at": datetime.now(timezone.utc).isoformat(),
+        "availability": availability,
+        "worktree_identity": "managed_target_checkout",
+        "branch": _git(root, "branch", "--show-current") or "UNAVAILABLE",
+        "head_sha": _git(root, "rev-parse", "HEAD") or "UNAVAILABLE",
+        "uncommitted": counts,
+        "meaning": "Current uncommitted worktree state only; never cumulative run delivery.",
+    }
+
+
+def _path_sets(names: str | None) -> dict[str, object]:
+    added: set[str] = set()
+    modified: set[str] = set()
+    removed: set[str] = set()
+    renamed: list[dict[str, str]] = []
+    if names:
+        for row in names.splitlines():
+            fields = row.split("\t")
+            if len(fields) < 2:
+                continue
+            status = fields[0]
+            if status.startswith("R") and len(fields) >= 3:
+                renamed.append({"from": fields[1], "to": fields[2]})
+            elif status.startswith("A"):
+                added.add(fields[1])
+            elif status.startswith("D"):
+                removed.add(fields[1])
+            else:
+                modified.add(fields[1])
+    unique = added | modified | removed | {item["from"] for item in renamed} | {item["to"] for item in renamed}
+    return {
+        "added": sorted(added), "modified": sorted(modified), "removed": sorted(removed),
+        "renamed": sorted(renamed, key=lambda item: (item["from"], item["to"])),
+        "total_unique_changed_paths": len(unique),
+    }
+
+
+def _phase_paths(root: Path, baseline: str | None, commit: str | None) -> dict[str, object] | None:
+    if not baseline or not commit or _git(root, "rev-parse", commit) is None:
+        return None
+    return _path_sets(_git(root, "diff", "--name-status", "-M", baseline, commit))
+
+
+def _command_activity(root: Path, run_id: str) -> dict[str, object]:
+    connection = open_storage(root)
+    try:
+        provider_rows = connection.execute(
+            "SELECT phase,role,COUNT(*) FROM provider_invocations "
+            "WHERE run_id=? AND provider='codex_cli' GROUP BY phase,role", (run_id,)
+        ).fetchall()
+        validation_rows = connection.execute(
+            "SELECT COUNT(*) FROM execution_validation_command_invocations WHERE run_id=?", (run_id,)
+        ).fetchone()
+    finally:
+        connection.close()
+    primary: dict[str, int] = {}
+    reviewers: dict[str, dict[str, int]] = {}
+    for phase, role, count in provider_rows:
+        if not isinstance(phase, str) or not isinstance(role, str) or not isinstance(count, int):
+            continue
+        if role.casefold().startswith("reviewer"):
+            reviewers.setdefault(role, {})[phase] = count
+        else:
+            primary[phase] = primary.get(phase, 0) + count
+    reviewer_total = sum(sum(phases.values()) for phases in reviewers.values())
+    primary_total = sum(primary.values())
+    host_validation_total = int(validation_rows[0]) if validation_rows and isinstance(validation_rows[0], int) else 0
+    return {
+        "metric_definition_version": 1,
+        "codex_command_definition": CODEX_COMMAND_DEFINITION,
+        "primary_codex_commands_by_phase": primary,
+        "primary_codex_commands_total": primary_total,
+        "reviewer_codex_commands_by_reviewer_and_phase": reviewers,
+        "reviewer_codex_commands_total": reviewer_total,
+        "host_validation_commands_by_phase": {"VALIDATION": host_validation_total},
+        "host_validation_commands_total": host_validation_total,
+        "overall_activity_total": primary_total + reviewer_total + host_validation_total,
+    }
+
+
+def cumulative_activity(root: Path, run_id: str) -> dict[str, object]:
+    """Project current persisted counters using the terminal metric definition."""
+    return _command_activity(root, run_id)
+
+
+def build_terminal_activity_summary(root: Path, state: object, bundle: object) -> dict[str, object]:
+    """Build the canonical terminal summary solely from persisted/Git evidence."""
+    run_id = str(getattr(state, "run_id"))
+    target = Path(str(getattr(bundle, "target_workspace")))
+    # The Evidence Bundle owns the authoritative transaction range.  Do not
+    # recompute it from a later lifecycle commit: that can exclude an earlier
+    # implementation merge or silently turn a known range into a different one.
+    baseline = getattr(bundle, "transaction_baseline_sha", None)
+    if not isinstance(baseline, str) or not baseline:
+        baseline = None
+    target_sha = str(getattr(bundle, "target_commit"))
+    renamed = [
+        {"from": source, "to": destination}
+        for source, destination in getattr(bundle, "files_renamed", ())
+        if isinstance(source, str) and isinstance(destination, str)
+    ]
+    delivery = {
+        "added": sorted(set(getattr(bundle, "files_added", ()))),
+        "modified": sorted(set(getattr(bundle, "files_modified", ()))),
+        "removed": sorted(set(getattr(bundle, "files_removed", ()))),
+        "renamed": sorted(renamed, key=lambda item: (item["from"], item["to"])),
+        # Evidence Bundle changed_files is the canonical run-delivery path
+        # count, including both sides of a proven rename.
+        "total_unique_changed_paths": len(set(getattr(bundle, "changed_files", ()))),
+    }
+    implementation = getattr(state, "implementation_merge_commit", None)
+    finalization = getattr(state, "finalization_merge_commit", None)
+    phase_attribution: dict[str, object] = {}
+    implementation_parent = _git(target, "rev-parse", f"{implementation}^") if implementation else None
+    if implementation:
+        phase_attribution["implementation"] = _phase_paths(target, implementation_parent, implementation) or "UNAVAILABLE"
+    if finalization:
+        phase_attribution["finalization"] = _phase_paths(target, implementation, finalization) or "UNAVAILABLE"
+    return {
+        "summary_version": EXECUTION_ACTIVITY_SUMMARY_VERSION,
+        "run_id": run_id,
+        "activity": _command_activity(root, run_id),
+        "terminal_delivery_diff": {
+            "authority": "AUTHORITATIVE_REPOSITORY_EVIDENCE",
+            "transaction_baseline_sha": baseline or "UNAVAILABLE",
+            "terminal_target_sha": target_sha,
+            **delivery,
+            "phase_attribution": phase_attribution or "UNAVAILABLE",
+            "implementation_pr": getattr(state, "implementation_pull_request", None),
+            "finalization_pr": getattr(state, "finalization_pull_request", None),
+            "reconciliation_pr": getattr(state, "reconciliation_pull_request", None),
+            "implementation_merge_commit": implementation,
+            "finalization_merge_commit": finalization,
+            "per_pr_changed_file_counts": "GitHub evidence scoped to each PR; never summed into this run total.",
+        },
+    }
+
+
+def persist_terminal_activity_summary(root: Path, summary: dict[str, object]) -> dict[str, object]:
+    """Insert once; legacy runs remain unavailable rather than inferred."""
+    run_id = summary.get("run_id")
+    if not isinstance(run_id, str):
+        raise EngineeringStorageError("Execution activity summary run identity is invalid.")
+    payload = json.dumps(summary, sort_keys=True, separators=(",", ":"))
+    connection = open_storage(root)
+    try:
+        connection.execute(
+            "INSERT OR IGNORE INTO execution_activity_summaries(run_id,summary_version,payload,persisted_at) VALUES(?,?,?,?)",
+            (run_id, EXECUTION_ACTIVITY_SUMMARY_VERSION, payload, datetime.now(timezone.utc).isoformat()),
+        )
+        row = connection.execute("SELECT payload FROM execution_activity_summaries WHERE run_id=?", (run_id,)).fetchone()
+    finally:
+        connection.close()
+    return json.loads(row[0]) if row else summary
+
+
+def terminal_activity_summary(root: Path, run_id: str) -> dict[str, object] | None:
+    """Return only a persisted canonical summary; never reconstruct legacy rows."""
+    try:
+        connection = open_storage(root)
+        try:
+            row = connection.execute("SELECT payload FROM execution_activity_summaries WHERE run_id=?", (run_id,)).fetchone()
+        finally:
+            connection.close()
+        return json.loads(row[0]) if row and isinstance(row[0], str) else None
+    except (EngineeringStorageError, json.JSONDecodeError):
+        return None

engineering_platform/execution_context.py

@@ -0,0 +1,132 @@
+"""Typed execution selection resolved before lifecycle admission."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from pathlib import Path
+
+from .execution_errors import RunnerError
+from .platform_api import PlatformConfiguration, PlatformConfigurationError
+from .providers import GitProvider
+
+
+@dataclass(frozen=True)
+class ExecutionContext:
+    execution_mode: str
+    host_repository: Path
+    target_repository: Path | None
+    lifecycle_policy: str
+    selected_preflight: str
+    action_intent: str = "MUTATING_DELIVERY"
+    run_id: str | None = None
+
+
+def _prompt_field_values(objective: str, label: str) -> tuple[str, ...]:
+    values: list[str] = []
+    lines = objective.splitlines()
+    for index, line in enumerate(lines):
+        candidate = line.strip()
+        prefix = f"{label}:"
+        if not candidate.casefold().startswith(prefix.casefold()):
+            continue
+        inline = candidate[len(prefix):].strip()
+        if inline:
+            values.append(inline)
+            continue
+        for candidate in lines[index + 1 :]:
+            value = candidate.strip()
+            if value:
+                values.append(value)
+                break
+    return tuple(values)
+
+
+ACTION_INTENTS = frozenset({"MUTATING_DELIVERY", "VALIDATION_ONLY"})
+
+
+def resolve_execution_context(
+    objective: str, host_repository: Path, *, action_intent: str = "MUTATING_DELIVERY"
+) -> ExecutionContext:
+    """Resolve the mode and selected target before lifecycle admission."""
+    if action_intent not in ACTION_INTENTS:
+        raise RunnerError("Execution action intent is invalid.")
+    modes = {line.split(":", 1)[1].strip().casefold() for line in objective.splitlines() if line.strip().casefold().startswith("execution mode:")}
+    if "genesis" not in modes:
+        return ExecutionContext("MANAGED", host_repository.resolve(), None, "managed", "managed_readiness", action_intent)
+    if modes != {"genesis"}:
+        raise RunnerError("Execution Mode: Genesis conflicts with another execution mode declaration.")
+    targets = _prompt_field_values(objective, "Target repository")
+    if not targets:
+        raise RunnerError("Genesis preflight blocked: prompt must declare one absolute Target repository path.")
+    if len(set(targets)) != 1:
+        raise RunnerError("Genesis preflight blocked: prompt declares conflicting Target repository paths.")
+    target = Path(targets[0]).expanduser()
+    if not target.is_absolute():
+        raise RunnerError("Genesis preflight blocked: Target repository path must be absolute.")
+    target = target.resolve()
+    if target == host_repository.resolve():
+        raise RunnerError("Genesis preflight blocked: Target repository cannot be the Engineering Platform host repository.")
+    return ExecutionContext("GENESIS", host_repository.resolve(), target, "local_only", "genesis_git_workspace", action_intent)
+
+
+def execution_mode_for(objective: str) -> str:
+    return "GENESIS" if any(line.strip().casefold() == "execution mode: genesis" for line in objective.splitlines()) else "MANAGED"
+
+
+def genesis_target_for(objective: str) -> Path | None:
+    targets = _prompt_field_values(objective, "Target repository")
+    return Path(targets[0]).expanduser() if len(set(targets)) == 1 else None
+
+
+def genesis_workspace_preflight(target: Path | None) -> str | None:
+    """Return a bounded, non-destructive Genesis workspace diagnostic."""
+    if target is None:
+        return "Genesis preflight blocked: prompt must declare an absolute Target repository path."
+    if not target.is_absolute() or not target.is_dir():
+        return "Genesis preflight blocked: Target repository path is absent or not a directory."
+    observed = GitProvider().execute(target, "git", "rev-parse", "--git-dir")
+    if observed.returncode:
+        return "Genesis preflight blocked: Target repository is not an accessible Git repository."
+    git_dir = Path(observed.stdout.strip())
+    if not git_dir.is_absolute():
+        git_dir = (target / git_dir).resolve()
+    if (git_dir / "index.lock").exists():
+        return f"Genesis preflight blocked: Git index lock exists at {git_dir / 'index.lock'}; it is not removed automatically."
+    if not os.access(git_dir, os.W_OK):
+        return f"Genesis preflight blocked: Git metadata directory is not writable: {git_dir}."
+    status = GitProvider().execute(target, "git", "status", "--porcelain", "--untracked-files=all")
+    if status.returncode:
+        return "Genesis preflight blocked: Target repository status could not be inspected."
+    return "Genesis preflight blocked: Target repository has tracked or untracked changes." if status.stdout.strip() else None
+
+
+def additional_workspace_write_roots(root: Path) -> tuple[Path, ...]:
+    """Resolve only configured, non-symlink Genesis write roots."""
+    if not (root / ".engineering" / "engineering-platform.local.json").is_file():
+        return ()
+    try:
+        policy = PlatformConfiguration.load(root).resolve_repository_authorization_policy()
+    except PlatformConfigurationError as error:
+        raise RunnerError(str(error)) from error
+    roots: list[Path] = []
+    for configured in policy.allowed_roots:
+        candidate = Path(configured.path).expanduser()
+        if candidate.is_symlink() or not candidate.is_dir() or candidate == Path(candidate.anchor):
+            raise RunnerError("Configured Engineering Workspace Root must be an existing non-root directory, not a symlink.")
+        roots.append(candidate.resolve())
+    for configured in policy.allowed_repositories:
+        candidate = Path(configured).expanduser()
+        if candidate.is_symlink() or not candidate.is_dir():
+            raise RunnerError("Configured Engineering Repository Allow-List entry must be an existing directory, not a symlink.")
+        roots.append(candidate.resolve().parent)
+    return tuple(dict.fromkeys(roots))
+
+
+def target_repository_authorization(root: Path, target: Path) -> str | None:
+    try:
+        authorization = PlatformConfiguration.load(root).authorize_target_repository(target, "GENESIS")
+    except PlatformConfigurationError as error:
+        return f"Genesis preflight blocked: {error}"
+    if authorization.authorized:
+        return None
+    return f"Genesis preflight blocked: WORKSPACE_TARGET_AUTHORIZED: {authorization.reason} Recovery: {authorization.recovery}"

engineering_platform/execution_errors.py

@@ -0,0 +1,42 @@
+"""Normalized errors shared by Execution Host responsibility modules."""
+from __future__ import annotations
+
+
+class RunnerError(RuntimeError):
+    """A fail-closed engineering-runner diagnostic."""
+
+
+class CodexInvocationError(RunnerError):
+    """Separates safe checkpoint diagnostics from bounded console evidence."""
+
+    def __init__(
+        self,
+        persistent_diagnostic: str,
+        console_detail: str,
+        *,
+        next_action: str = "inspect_codex_cli",
+        terminal_condition: str = "codex_invocation_failed",
+        interruption_reason: str | None = None,
+    ) -> None:
+        super().__init__(persistent_diagnostic)
+        self.console_detail = console_detail
+        self.next_action = next_action
+        self.terminal_condition = terminal_condition
+        self.interruption_reason = interruption_reason
+
+    @property
+    def provider_turn_interrupted(self) -> bool:
+        """Whether provider evidence proves a turn ended without a result."""
+        return self.terminal_condition == "provider_turn_interrupted" and bool(self.interruption_reason)
+
+
+class CodexHandoffTimeout(RunnerError):
+    """A bounded agent hand-off exceeded its host-owned deadline."""
+
+
+class ProviderReadinessBlocked(RunnerError):
+    """A durable checkpoint is waiting for explicit local provider recovery."""
+
+    def __init__(self, state: object) -> None:
+        super().__init__("Provider readiness must be repaired before this action can continue.")
+        self.state = state

engineering_platform/execution_evidence.py

@@ -0,0 +1,24 @@
+"""Typed, read-only terminal evidence shared by reporting and lifecycle coordination."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TerminalEvidenceBundle:
+    target_workspace: str
+    target_repository: str
+    target_branch: str
+    target_commit: str
+    worktree_state: str
+    changed_files: tuple[str, ...]
+    files_added: tuple[str, ...]
+    files_modified: tuple[str, ...]
+    files_removed: tuple[str, ...]
+    files_renamed: tuple[tuple[str, str], ...]
+    diff_check: str
+    transaction_baseline: str
+    transaction_baseline_sha: str | None
+    resulting_commit: str | None
+    lease: dict[str, object]
+    readiness: dict[str, object] | None