prizmkit 1.1.100 → 1.1.101

package/bundled/dev-pipeline/prizmkit_runtime/heartbeat.py

@@ -0,0 +1,256 @@
+"""Heartbeat and stale-session primitives."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .processes import ProcessHandle, is_process_running, terminate_process_tree
+
+
+@dataclass(frozen=True)
+class HeartbeatConfig:
+    """Heartbeat file and timeout policy for runtime porting."""
+
+    heartbeat_file: Path
+    session_log: Path | None = None
+    progress_file: Path | None = None
+    marker_dir: Path | None = None
+    interval_seconds: float = 30
+    stale_after_seconds: float = 300
+    kill_after_seconds: float = 600
+    grace_seconds: float = 10
+
+
+@dataclass(frozen=True)
+class HeartbeatState:
+    """Current heartbeat freshness observation."""
+
+    last_seen_epoch: float | None
+    stale: bool
+    details: str
+    stale_seconds: float = 0
+    log_size: int = 0
+    progress_signature: str = ""
+    child_activity_signature: str = ""
+
+
+@dataclass(frozen=True)
+class HeartbeatStopResult:
+    """Outcome from stopping a heartbeat monitor."""
+
+    killed: bool
+    reason: str | None
+    marker_path: Path | None
+    state: HeartbeatState
+
+
+def _file_size(path: Path | None) -> int:
+    if path is None:
+        return 0
+    try:
+        return path.stat().st_size
+    except OSError:
+        return 0
+
+
+def _progress_signature(path: Path | None) -> tuple[str, str]:
+    if path is None or not path.is_file():
+        return "", ""
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return "", ""
+    child_signature = str(data.get("child_activity_signature") or "")
+    signature = json.dumps(
+        [
+            data.get("current_phase") or "",
+            data.get("current_tool") or "",
+            int(data.get("message_count") or 0),
+            int(data.get("total_tool_calls") or 0),
+            int(data.get("active_subagent_count") or 0),
+            int(data.get("subagent_spawn_count") or 0),
+            child_signature,
+            int(data.get("child_total_bytes") or 0),
+            data.get("fatal_error_code") or "",
+            data.get("terminal_result_text") or "",
+        ],
+        separators=(",", ":"),
+    )
+    return signature, child_signature
+
+
+def observe_heartbeat_state(
+    config: HeartbeatConfig,
+    previous: HeartbeatState | None = None,
+) -> HeartbeatState:
+    """Observe log/progress activity and compute staleness."""
+    now = time.time()
+    log_size = _file_size(config.session_log)
+    progress_signature, child_signature = _progress_signature(config.progress_file)
+    prev_log_size = previous.log_size if previous else 0
+    progressed = (
+        previous is None
+        or log_size > prev_log_size
+        or (progress_signature and progress_signature != previous.progress_signature)
+        or (child_signature and child_signature != previous.child_activity_signature)
+    )
+    stale_seconds = 0 if progressed else (previous.stale_seconds + config.interval_seconds if previous else 0)
+    stale = bool(config.stale_after_seconds > 0 and stale_seconds >= config.stale_after_seconds)
+    details = "progress" if progressed else "no progress"
+    return HeartbeatState(
+        last_seen_epoch=now if progressed else (previous.last_seen_epoch if previous else now),
+        stale=stale,
+        details=details,
+        stale_seconds=stale_seconds,
+        log_size=log_size,
+        progress_signature=progress_signature,
+        child_activity_signature=child_signature,
+    )
+
+
+def _utc_marker_time() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def _progress_fatal_error_code(path: Path | None) -> str:
+    if path is None or not path.is_file():
+        return ""
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return ""
+    return str(data.get("fatal_error_code") or "")
+
+
+def write_stale_marker(
+    marker_dir: Path,
+    *,
+    reason: str,
+    stale_seconds: float,
+    threshold: float,
+    fatal_error_code: str | None = None,
+) -> Path:
+    """Write a stale/fatal marker compatible with shell artifact shape."""
+    marker_dir.mkdir(parents=True, exist_ok=True)
+    marker_path = marker_dir / "stale-kill.json"
+    payload = {
+        "killed_at": _utc_marker_time(),
+        "reason": reason,
+        "stale_seconds": int(stale_seconds),
+        "threshold": int(threshold),
+    }
+    if fatal_error_code:
+        payload["fatal_error_code"] = fatal_error_code
+    marker_path.write_text(json.dumps(payload, sort_keys=True) + "\n", encoding="utf-8")
+    return marker_path
+
+
+def write_fatal_marker(
+    marker_dir: Path,
+    *,
+    fatal_error_code: str,
+    stale_seconds: float,
+    threshold: float,
+) -> tuple[Path, Path]:
+    """Write shell-compatible fatal-error and stale-kill marker files."""
+    marker_dir.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "killed_at": _utc_marker_time(),
+        "reason": fatal_error_code,
+        "fatal_error_code": fatal_error_code,
+        "stale_seconds": int(stale_seconds),
+        "threshold": int(threshold),
+    }
+    fatal_path = marker_dir / "fatal-error.json"
+    stale_path = marker_dir / "stale-kill.json"
+    encoded = json.dumps(payload, sort_keys=True) + "\n"
+    fatal_path.write_text(encoded, encoding="utf-8")
+    stale_path.write_text(encoded, encoding="utf-8")
+    return fatal_path, stale_path
+
+
+class HeartbeatMonitor:
+    """Background heartbeat monitor that can stale-kill a process tree."""
+
+    def __init__(self, handle: ProcessHandle, config: HeartbeatConfig):
+        self.handle = handle
+        self.config = config
+        self._stop_event = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._state = HeartbeatState(last_seen_epoch=None, stale=False, details="not started")
+        self._killed = False
+        self._reason: str | None = None
+        self._marker_path: Path | None = None
+
+    @property
+    def state(self) -> HeartbeatState:
+        return self._state
+
+    def start(self) -> None:
+        if self._thread is not None:
+            return
+        self.config.heartbeat_file.parent.mkdir(parents=True, exist_ok=True)
+        self.config.heartbeat_file.write_text("started\n", encoding="utf-8")
+        self._thread = threading.Thread(target=self._run, name="prizmkit-heartbeat", daemon=True)
+        self._thread.start()
+
+    def _run(self) -> None:
+        while not self._stop_event.wait(max(0.01, self.config.interval_seconds)):
+            if not is_process_running(self.handle):
+                break
+            self._state = observe_heartbeat_state(self.config, self._state)
+            self.config.heartbeat_file.write_text(
+                json.dumps(
+                    {
+                        "last_seen_epoch": self._state.last_seen_epoch,
+                        "stale": self._state.stale,
+                        "stale_seconds": self._state.stale_seconds,
+                        "details": self._state.details,
+                    },
+                    sort_keys=True,
+                )
+                + "\n",
+                encoding="utf-8",
+            )
+            fatal_error_code = _progress_fatal_error_code(self.config.progress_file)
+            if fatal_error_code:
+                marker_dir = self.config.marker_dir or (self.config.session_log.parent if self.config.session_log else self.config.heartbeat_file.parent)
+                _fatal_path, self._marker_path = write_fatal_marker(
+                    marker_dir,
+                    fatal_error_code=fatal_error_code,
+                    stale_seconds=self._state.stale_seconds,
+                    threshold=self.config.stale_after_seconds,
+                )
+                terminate_process_tree(self.handle, fatal_error_code, grace_seconds=self.config.grace_seconds)
+                self._killed = True
+                self._reason = fatal_error_code
+                break
+            if self._state.stale and self.config.kill_after_seconds > 0:
+                marker_dir = self.config.marker_dir or (self.config.session_log.parent if self.config.session_log else self.config.heartbeat_file.parent)
+                self._marker_path = write_stale_marker(
+                    marker_dir,
+                    reason="stale_session",
+                    stale_seconds=self._state.stale_seconds,
+                    threshold=self.config.stale_after_seconds,
+                )
+                terminate_process_tree(self.handle, "stale_session", grace_seconds=self.config.grace_seconds)
+                self._killed = True
+                self._reason = "stale_session"
+                break
+
+    def stop(self) -> HeartbeatStopResult:
+        self._stop_event.set()
+        if self._thread is not None:
+            self._thread.join(timeout=max(1.0, self.config.interval_seconds * 2))
+        return HeartbeatStopResult(
+            killed=self._killed,
+            reason=self._reason,
+            marker_path=self._marker_path,
+            state=self._state,
+        )

package/bundled/dev-pipeline/prizmkit_runtime/interoperability.py

@@ -0,0 +1,109 @@
+"""Interoperability contracts for Python utility entrypoints."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .paths import RuntimePaths, resolve_runtime_paths
+
+UTILITY_ENTRYPOINTS = {
+    "check-session-status": "scripts/check-session-status.py",
+    "detect-stuck": "scripts/detect-stuck.py",
+    "generate-bootstrap-prompt": "scripts/generate-bootstrap-prompt.py",
+    "generate-bugfix-prompt": "scripts/generate-bugfix-prompt.py",
+    "generate-recovery-prompt": "scripts/generate-recovery-prompt.py",
+    "generate-refactor-prompt": "scripts/generate-refactor-prompt.py",
+    "init-bugfix-pipeline": "scripts/init-bugfix-pipeline.py",
+    "init-dev-team": "scripts/init-dev-team.py",
+    "init-pipeline": "scripts/init-pipeline.py",
+    "init-refactor-pipeline": "scripts/init-refactor-pipeline.py",
+    "parse-stream-progress": "scripts/parse-stream-progress.py",
+    "patch-completion-notes": "scripts/patch-completion-notes.py",
+    "prizmkit-test-gate": "scripts/prizmkit-test-gate.py",
+    "update-bug-status": "scripts/update-bug-status.py",
+    "update-checkpoint": "scripts/update-checkpoint.py",
+    "update-feature-status": "scripts/update-feature-status.py",
+    "update-refactor-status": "scripts/update-refactor-status.py",
+}
+
+UTILITY_LIBRARY_ONLY = {
+    "continuation.py": "shared continuation helpers imported by prompt generators",
+    "utils.py": "shared utility helpers imported by runtime scripts",
+}
+
+ENTRYPOINT_GROUPS = {
+    "utility": UTILITY_ENTRYPOINTS,
+}
+
+
+@dataclass(frozen=True)
+class ScriptInvocation:
+    """Description of a Python runtime utility invocation."""
+
+    script_path: Path
+    arguments: tuple[str, ...] = ()
+    cwd: Path | None = None
+    environment_overrides: Mapping[str, str] = field(default_factory=dict)
+    entrypoint_kind: str = "unknown"
+    entrypoint_name: str = "unknown"
+
+    def command_line(self) -> tuple[str, ...]:
+        """Return the executable command line for this invocation."""
+        return (str(self.script_path), *self.arguments)
+
+
+def _resolve_script_path(kind: str, name: str, paths: RuntimePaths) -> Path:
+    group = ENTRYPOINT_GROUPS.get(kind)
+    if group is None:
+        valid = ", ".join(sorted(ENTRYPOINT_GROUPS))
+        raise KeyError(f"Unknown entrypoint kind '{kind}'. Valid kinds: {valid}")
+    rel_path = group.get(name)
+    if rel_path is None:
+        valid = ", ".join(sorted(group))
+        raise KeyError(f"Unknown {kind} entrypoint '{name}'. Valid names: {valid}")
+    return paths.pipeline_root / rel_path
+
+
+def describe_existing_entrypoint(
+    kind: str,
+    name: str,
+    *,
+    paths: RuntimePaths | None = None,
+    arguments: Sequence[str] = (),
+    cwd: str | Path | None = None,
+    env: Mapping[str, str] | None = None,
+) -> ScriptInvocation:
+    """Describe a Python utility entrypoint without executing it."""
+    runtime_paths = paths or resolve_runtime_paths()
+    return ScriptInvocation(
+        script_path=_resolve_script_path(kind, name, runtime_paths),
+        arguments=tuple(arguments),
+        cwd=Path(cwd).expanduser().resolve() if cwd is not None else runtime_paths.project_root,
+        environment_overrides={} if env is None else dict(env),
+        entrypoint_kind=kind,
+        entrypoint_name=name,
+    )
+
+
+def run_existing_entrypoint(invocation: ScriptInvocation) -> subprocess.CompletedProcess[str]:
+    """Run a Python utility entrypoint through a standard-library subprocess bridge."""
+    process_env = None
+    if invocation.environment_overrides:
+        process_env = {**os.environ, **invocation.environment_overrides}
+    command = invocation.command_line()
+    if invocation.script_path.suffix == ".py":
+        command = (sys.executable, *command)
+    return subprocess.run(
+        command,
+        cwd=invocation.cwd,
+        env=process_env,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        check=False,
+    )

package/bundled/dev-pipeline/prizmkit_runtime/paths.py

@@ -0,0 +1,110 @@
+"""Cross-platform path contracts for the unified runtime skeleton."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class RuntimePaths:
+    """Cohesive runtime path model derived with pathlib only."""
+
+    pipeline_root: Path
+    project_root: Path
+    prizmkit_dir: Path
+    plans_dir: Path
+    state_dir: Path
+    logs_dir: Path
+    specs_dir: Path
+    feature_plan: Path
+    bugfix_plan: Path
+    refactor_plan: Path
+    feature_state_dir: Path
+    bugfix_state_dir: Path
+    refactor_state_dir: Path
+    recovery_state_dir: Path
+    layout: str
+
+    def path_values(self) -> tuple[Path, ...]:
+        """Return all path fields for tests and diagnostics."""
+        return (
+            self.pipeline_root,
+            self.project_root,
+            self.prizmkit_dir,
+            self.plans_dir,
+            self.state_dir,
+            self.logs_dir,
+            self.specs_dir,
+            self.feature_plan,
+            self.bugfix_plan,
+            self.refactor_plan,
+            self.feature_state_dir,
+            self.bugfix_state_dir,
+            self.refactor_state_dir,
+            self.recovery_state_dir,
+        )
+
+
+def _default_pipeline_root() -> Path:
+    return Path(__file__).resolve().parents[1]
+
+
+def _normalize_path(value: str | Path | None) -> Path | None:
+    if value is None:
+        return None
+    return Path(value).expanduser().resolve()
+
+
+def _derive_layout(pipeline_root: Path) -> str:
+    if pipeline_root.name == "dev-pipeline" and pipeline_root.parent.name == ".prizmkit":
+        return "installed"
+    return "framework-source"
+
+
+def resolve_runtime_paths(
+    pipeline_root: str | Path | None = None,
+    project_root: str | Path | None = None,
+    prizmkit_dir: str | Path | None = None,
+) -> RuntimePaths:
+    """Resolve runtime paths for framework-source or installed layouts."""
+    resolved_pipeline_root = _normalize_path(pipeline_root) or _default_pipeline_root()
+    layout = _derive_layout(resolved_pipeline_root)
+
+    resolved_project_root = _normalize_path(project_root)
+    resolved_prizmkit_dir = _normalize_path(prizmkit_dir)
+
+    if resolved_project_root is None:
+        if layout == "installed":
+            resolved_project_root = resolved_pipeline_root.parent.parent
+        else:
+            resolved_project_root = resolved_pipeline_root.parent
+
+    if resolved_prizmkit_dir is None:
+        if layout == "installed":
+            resolved_prizmkit_dir = resolved_pipeline_root.parent
+        else:
+            resolved_prizmkit_dir = resolved_project_root / ".prizmkit"
+
+    plans_dir = resolved_prizmkit_dir / "plans"
+    state_dir = resolved_prizmkit_dir / "state"
+    logs_dir = state_dir / "logs"
+    specs_dir = resolved_prizmkit_dir / "specs"
+
+    return RuntimePaths(
+        pipeline_root=resolved_pipeline_root,
+        project_root=resolved_project_root,
+        prizmkit_dir=resolved_prizmkit_dir,
+        plans_dir=plans_dir,
+        state_dir=state_dir,
+        logs_dir=logs_dir,
+        specs_dir=specs_dir,
+        feature_plan=plans_dir / "feature-list.json",
+        bugfix_plan=plans_dir / "bug-fix-list.json",
+        refactor_plan=plans_dir / "refactor-list.json",
+        feature_state_dir=state_dir / "features",
+        bugfix_state_dir=state_dir / "bugfix",
+        refactor_state_dir=state_dir / "refactor",
+        recovery_state_dir=state_dir / "recovery",
+        layout=layout,
+    )