prizmkit 1.1.99 → 1.1.101

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

@@ -0,0 +1,552 @@
+"""AI session launch, command construction, logging, and raw signal capture."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import queue
+import shutil
+import subprocess
+import threading
+import time
+from collections import Counter
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .heartbeat import HeartbeatConfig, HeartbeatMonitor, write_stale_marker
+from .processes import ProcessHandle, ProcessSpec, launch_process, terminate_process_tree
+from .status import ProgressSummary
+
+
+@dataclass(frozen=True)
+class StreamJsonSupport:
+    """Detected stream-json capability for an AI CLI."""
+
+    enabled: bool
+    format: str = ""
+    source: str = ""
+    notes: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class AISessionConfig:
+    """Inputs needed to launch one AI CLI session."""
+
+    cli_command: str
+    platform: str
+    model: str | None
+    prompt_path: Path
+    cwd: Path
+    log_path: Path | None = None
+    backup_log_path: Path | None = None
+    progress_path: Path | None = None
+    heartbeat_path: Path | None = None
+    effort: str | None = None
+    verbose: bool = False
+    use_stream_json: bool = False
+    stream_json_format: str = ""
+    permission_mode: str = "dangerously-skip-permissions"
+    total_timeout_seconds: float | None = None
+    stale_kill_threshold_seconds: float = 0
+    stale_kill_grace_seconds: float = 10
+    codex_subagent_timeout_seconds: int = 3300
+    extra_args: tuple[str, ...] = ()
+    environment_overrides: Mapping[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class AISessionCommand:
+    """Provider-specific command shape."""
+
+    argv: tuple[str, ...]
+    stdin_text: str | None
+    provider: str
+    prompt_mode: str
+
+
+@dataclass(frozen=True)
+class LogRecoveryResult:
+    """Result from backup session-log recovery."""
+
+    recovered: bool
+    cleaned_backup: bool
+    main_size: int
+    backup_size: int
+    session_log: Path
+    backup_log: Path
+
+
+@dataclass(frozen=True)
+class AISessionResult:
+    """Raw runtime signals from a session run, not final pipeline status."""
+
+    command: AISessionCommand
+    exit_code: int | None
+    timed_out: bool
+    termination_reason: str | None
+    stale_marker: Path | None
+    fatal_error_code: str
+    progress_summary: ProgressSummary
+    session_log: Path
+    backup_log: Path
+    log_recovery: LogRecoveryResult | None
+    started_epoch: float
+    ended_epoch: float
+
+
+HelpRunner = Callable[[Sequence[str]], str]
+
+
+def _normalize_platform(platform: str | None) -> str:
+    normalized = (platform or "").strip().lower()
+    return normalized if normalized in {"claude", "codex", "codebuddy"} else "codebuddy"
+
+
+def _prompt_text(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+def _default_help_runner(command: Sequence[str]) -> str:
+    completed = subprocess.run(
+        list(command),
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        check=False,
+    )
+    return completed.stdout or ""
+
+
+def detect_stream_json_support(
+    cli_command: str,
+    platform: str | None,
+    help_runner: HelpRunner | None = None,
+) -> StreamJsonSupport:
+    """Detect stream-json support using shell-compatible provider rules."""
+    normalized = _normalize_platform(platform)
+    command_name = Path(str(cli_command).split()[0].strip("'\"")).name.lower()
+    if normalized == "codebuddy" or command_name == "cbc":
+        return StreamJsonSupport(True, "stream-json", "codebuddy-default")
+    runner = help_runner or _default_help_runner
+    if normalized == "codex":
+        help_output = runner((cli_command, "exec", "--help"))
+        if "--json" in help_output:
+            return StreamJsonSupport(True, "codex-json", "codex-exec-help")
+        return StreamJsonSupport(False, "", "codex-exec-help", ("--json not found",))
+    help_output = runner((cli_command, "--help"))
+    if "stream-json" in help_output:
+        return StreamJsonSupport(True, "stream-json", "cli-help")
+    return StreamJsonSupport(False, "", "cli-help", ("stream-json not found",))
+
+
+def _codex_subagent_timeout(config: AISessionConfig) -> int:
+    if config.codex_subagent_timeout_seconds > 0:
+        return config.codex_subagent_timeout_seconds
+    return 3300
+
+
+def build_ai_session_command(config: AISessionConfig) -> AISessionCommand:
+    """Build provider-specific AI CLI argv without spawning a process."""
+    platform = _normalize_platform(config.platform)
+    prompt = _prompt_text(config.prompt_path)
+    if platform == "claude":
+        argv = [config.cli_command, "-p", prompt, "--dangerously-skip-permissions"]
+        if config.verbose or config.use_stream_json:
+            argv.append("--verbose")
+        if config.use_stream_json:
+            argv.extend(["--output-format", "stream-json"])
+        if config.effort:
+            argv.extend(["--effort", config.effort])
+        if config.model:
+            argv.extend(["--model", config.model])
+        argv.extend(config.extra_args)
+        return AISessionCommand(tuple(argv), None, "claude", "argument")
+
+    if platform == "codex":
+        argv = [
+            config.cli_command,
+            "--ask-for-approval",
+            "never",
+            "--sandbox",
+            "danger-full-access",
+        ]
+        timeout = _codex_subagent_timeout(config)
+        if timeout > 0:
+            argv.extend(["--config", f"agents.job_max_runtime_seconds={timeout}"])
+        argv.extend(["exec", "--cd", str(config.cwd), "--skip-git-repo-check"])
+        if config.use_stream_json:
+            argv.append("--json")
+        if config.model:
+            argv.extend(["--model", config.model])
+        if config.effort:
+            argv.extend(["--config", f"model_reasoning_effort={config.effort}"])
+        argv.extend(config.extra_args)
+        argv.append("-")
+        return AISessionCommand(tuple(argv), prompt, "codex", "stdin")
+
+    argv = [config.cli_command, "--print", "-y"]
+    if config.verbose:
+        argv.append("--verbose")
+    if config.use_stream_json:
+        argv.extend(["--output-format", "stream-json"])
+    if config.effort:
+        argv.extend(["--effort", config.effort])
+    if config.model:
+        argv.extend(["--model", config.model])
+    argv.extend(config.extra_args)
+    return AISessionCommand(tuple(argv), prompt, "codebuddy", "stdin")
+
+
+def default_backup_log_path(session_log: Path, home: Path | None = None) -> Path:
+    """Return the shell-compatible home backup path for a session log."""
+    session_dir = session_log.parent.parent
+    session_id = session_dir.name
+    root = home or Path.home()
+    return root / ".prizmkit" / "session-backups" / f"{session_id}.log"
+
+
+def write_session_preamble(session_log: Path, backup_log: Path, prompt_path: Path, model: str | None) -> None:
+    """Write the session preamble to both primary and backup logs."""
+    session_log.parent.mkdir(parents=True, exist_ok=True)
+    backup_log.parent.mkdir(parents=True, exist_ok=True)
+    preamble = "\n".join(
+        [
+            "=== PRIZMKIT SESSION START ===",
+            f"Prompt: {prompt_path}",
+            f"Model: {model or 'default'}",
+            f"Started at epoch: {time.time():.6f}",
+            "--- OUTPUT BELOW ---",
+            "",
+        ]
+    )
+    session_log.write_text(preamble, encoding="utf-8")
+    backup_log.write_text(preamble, encoding="utf-8")
+
+
+def recover_session_log(session_log: Path, backup_log: Path, min_size: int = 1024) -> LogRecoveryResult:
+    """Recover a truncated/unlinked session.log from the home backup."""
+    main_size = session_log.stat().st_size if session_log.is_file() else 0
+    backup_size = backup_log.stat().st_size if backup_log.is_file() else 0
+    recovered = False
+    if backup_log.is_file() and main_size < min_size and backup_size > main_size:
+        session_log.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(backup_log, session_log)
+        recovered = True
+    cleaned = False
+    if backup_log.exists():
+        backup_log.unlink()
+        cleaned = True
+    return LogRecoveryResult(
+        recovered=recovered,
+        cleaned_backup=cleaned,
+        main_size=main_size,
+        backup_size=backup_size,
+        session_log=session_log,
+        backup_log=backup_log,
+    )
+
+
+def _permission_denial_text(event: object) -> str:
+    text = json.dumps(event, ensure_ascii=False) if isinstance(event, dict) else str(event)
+    lower = text.lower()
+    markers = (
+        "permission denied",
+        "permission_denied",
+        "permission denial",
+        "denied by user",
+        "user denied",
+        "not permitted",
+    )
+    return text[:500] if any(marker in lower for marker in markers) else ""
+
+
+def parse_stream_progress_lines(lines: Sequence[str]) -> ProgressSummary:
+    """Parse raw JSONL lines into additive provider-neutral progress metadata."""
+    event_type_counts: Counter[str] = Counter()
+    permission_denials: list[str] = []
+    claude_session_id = ""
+    cb_session_id = ""
+    result_subtype = ""
+    stop_reason = ""
+    has_usage = False
+    fatal_error_code = ""
+    terminal_result_text = ""
+    errors: list[str] = []
+
+    for raw_line in lines:
+        line = raw_line.strip()
+        if not line:
+            continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            denial = _permission_denial_text(line)
+            if denial:
+                permission_denials.append(denial)
+            continue
+        if not isinstance(event, dict):
+            continue
+        event_type = str(event.get("type") or "")
+        if event_type:
+            event_type_counts[event_type] += 1
+        if isinstance(event.get("sessionId"), str) and not cb_session_id:
+            cb_session_id = event["sessionId"].strip()
+        if event_type == "system" and event.get("subtype") == "init":
+            session_id = event.get("session_id")
+            if isinstance(session_id, str):
+                claude_session_id = session_id.strip()
+        if event_type == "result":
+            result_subtype = str(event.get("subtype") or event.get("result_subtype") or "")
+            stop_reason = str(event.get("stop_reason") or "")
+            terminal_result_text = str(event.get("result") or event.get("message") or "")[:1000]
+        if event_type in {"turn.failed", "error"}:
+            message = event.get("error") or event.get("message") or event
+            errors.append(str(message)[:500])
+        if event.get("usage") not in (None, "", {}):
+            has_usage = True
+        for key in ("fatal_error_code", "api_error_code", "error_code"):
+            value = event.get(key)
+            if value:
+                fatal_error_code = str(value)
+                break
+        error_obj = event.get("error")
+        if isinstance(error_obj, dict):
+            value = error_obj.get("code") or error_obj.get("type")
+            if value and not fatal_error_code:
+                fatal_error_code = str(value)
+            message = error_obj.get("message")
+            if message:
+                errors.append(str(message)[:500])
+        denial = _permission_denial_text(event)
+        if denial:
+            permission_denials.append(denial)
+
+    return ProgressSummary(
+        event_type_counts=dict(event_type_counts),
+        claude_session_id=claude_session_id,
+        cb_session_id=cb_session_id,
+        result_subtype=result_subtype,
+        stop_reason=stop_reason,
+        has_usage=has_usage,
+        permission_denial_count=len(permission_denials),
+        permission_denials=tuple(permission_denials[-10:]),
+        fatal_error_code=fatal_error_code,
+        terminal_result_text=terminal_result_text,
+        errors=tuple(errors[-10:]),
+    )
+
+
+def _load_progress_tracker_class():
+    parser_path = Path(__file__).resolve().parents[1] / "scripts" / "parse-stream-progress.py"
+    spec = importlib.util.spec_from_file_location("prizmkit_parse_stream_progress", parser_path)
+    if spec is None or spec.loader is None:
+        return None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return getattr(module, "ProgressTracker", None)
+
+
+def _write_progress_summary(progress_path: Path | None, summary: ProgressSummary) -> None:
+    if progress_path is None:
+        return
+    progress_path.parent.mkdir(parents=True, exist_ok=True)
+    progress_path.write_text(json.dumps(summary.to_dict(), indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def _reader_thread(
+    pipe,
+    session_log: Path,
+    backup_log: Path,
+    output_queue: "queue.Queue[str]",
+    progress_path: Path | None = None,
+) -> None:
+    lines: list[str] = []
+    tracker = None
+    tracker_class = _load_progress_tracker_class() if progress_path is not None else None
+    if tracker_class is not None:
+        try:
+            tracker = tracker_class(session_log)
+        except Exception:
+            tracker = None
+    try:
+        for line in iter(pipe.readline, ""):
+            if not line:
+                break
+            with session_log.open("a", encoding="utf-8") as main_fh:
+                main_fh.write(line)
+            with backup_log.open("a", encoding="utf-8") as backup_fh:
+                backup_fh.write(line)
+            output_queue.put(line)
+            lines.append(line)
+            if progress_path is not None:
+                if tracker is not None:
+                    stripped = line.strip()
+                    if stripped:
+                        try:
+                            tracker.process_event(json.loads(stripped))
+                        except json.JSONDecodeError:
+                            tracker.last_text_snippet = stripped[:120]
+                            tracker._detect_terminal_error(stripped, require_error_context=True)
+                    data = tracker.to_dict()
+                    progress_path.parent.mkdir(parents=True, exist_ok=True)
+                    progress_path.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+                else:
+                    _write_progress_summary(progress_path, parse_stream_progress_lines(lines))
+    finally:
+        try:
+            pipe.close()
+        except Exception:
+            pass
+
+
+def _merged_progress(existing: Mapping[str, object], summary: ProgressSummary) -> dict[str, object]:
+    """Merge final summary into richer live parser output without erasing signals."""
+    merged = dict(existing)
+    for key, value in summary.to_dict().items():
+        current = merged.get(key)
+        if key == "event_type_counts" and isinstance(current, dict) and isinstance(value, dict):
+            combined = dict(value)
+            combined.update(current)
+            merged[key] = combined
+        elif current in (None, "", [], {}):
+            merged[key] = value
+        elif current == 0 and key == "permission_denial_count":
+            merged[key] = value
+        elif key not in merged:
+            merged[key] = value
+    return merged
+
+
+def _summary_from_progress_dict(data: Mapping[str, object], fallback: ProgressSummary) -> ProgressSummary:
+    """Build ProgressSummary from merged progress data."""
+    event_counts = data.get("event_type_counts")
+    permission_denials = data.get("permission_denials")
+    errors = data.get("errors")
+    return ProgressSummary(
+        event_type_counts=event_counts if isinstance(event_counts, Mapping) else fallback.event_type_counts,
+        claude_session_id=str(data.get("claude_session_id") or fallback.claude_session_id),
+        cb_session_id=str(data.get("cb_session_id") or fallback.cb_session_id),
+        result_subtype=str(data.get("result_subtype") or fallback.result_subtype),
+        stop_reason=str(data.get("stop_reason") or fallback.stop_reason),
+        has_usage=bool(data.get("has_usage") or fallback.has_usage),
+        permission_denial_count=int(data.get("permission_denial_count") or fallback.permission_denial_count or 0),
+        permission_denials=tuple(str(item) for item in permission_denials) if isinstance(permission_denials, list) else fallback.permission_denials,
+        fatal_error_code=str(data.get("fatal_error_code") or fallback.fatal_error_code),
+        terminal_result_text=str(data.get("terminal_result_text") or fallback.terminal_result_text),
+        errors=tuple(str(item) for item in errors) if isinstance(errors, list) else fallback.errors,
+    )
+
+
+class AISessionLauncher:
+    """AI session launcher returning raw runtime signals."""
+
+    def __init__(self, config: AISessionConfig):
+        self.config = config
+
+    def describe(self) -> str:
+        """Describe this launch contract without spawning a process."""
+        model_text = self.config.model or "CLI default model"
+        return f"AI session launch boundary: {self.config.platform} via {self.config.cli_command}, model={model_text}"
+
+    def run(self) -> AISessionResult:
+        """Run the AI CLI session and capture logs/progress/raw outcome signals."""
+        command = build_ai_session_command(self.config)
+        session_log = self.config.log_path or self.config.cwd / ".prizmkit" / "state" / "session.log"
+        backup_log = self.config.backup_log_path or default_backup_log_path(session_log)
+        write_session_preamble(session_log, backup_log, self.config.prompt_path, self.config.model)
+
+        spec = ProcessSpec(
+            command=command.argv,
+            cwd=self.config.cwd,
+            environment_overrides=self.config.environment_overrides,
+            environment_unsets=("CLAUDECODE",),
+            stdin_text=command.stdin_text,
+        )
+        handle = launch_process(spec, stderr=subprocess.STDOUT)
+        assert handle.popen is not None
+        output_queue: queue.Queue[str] = queue.Queue()
+        reader = threading.Thread(
+            target=_reader_thread,
+            args=(handle.popen.stdout, session_log, backup_log, output_queue, self.config.progress_path),
+            daemon=True,
+        )
+        reader.start()
+        if handle.popen.stdin is not None:
+            if command.stdin_text is not None:
+                handle.popen.stdin.write(command.stdin_text)
+            handle.popen.stdin.close()
+
+        heartbeat = None
+        heartbeat_path = self.config.heartbeat_path
+        if heartbeat_path is None and self.config.stale_kill_threshold_seconds > 0:
+            heartbeat_path = session_log.with_name("heartbeat.json")
+        if heartbeat_path is not None:
+            heartbeat = HeartbeatMonitor(
+                handle,
+                HeartbeatConfig(
+                    heartbeat_file=heartbeat_path,
+                    session_log=session_log,
+                    progress_file=self.config.progress_path,
+                    marker_dir=session_log.parent,
+                    interval_seconds=0.1,
+                    stale_after_seconds=self.config.stale_kill_threshold_seconds,
+                    kill_after_seconds=self.config.stale_kill_threshold_seconds,
+                    grace_seconds=self.config.stale_kill_grace_seconds,
+                ),
+            )
+            heartbeat.start()
+
+        started = time.time()
+        timed_out = False
+        termination_reason = None
+        stale_marker = None
+        try:
+            handle.popen.wait(timeout=self.config.total_timeout_seconds)
+        except subprocess.TimeoutExpired:
+            timed_out = True
+            termination_reason = "timeout"
+            terminate_process_tree(handle, "timeout", grace_seconds=self.config.stale_kill_grace_seconds)
+        reader.join(timeout=5)
+        heartbeat_result = heartbeat.stop() if heartbeat is not None else None
+        if heartbeat_result and heartbeat_result.killed:
+            termination_reason = heartbeat_result.reason
+            stale_marker = heartbeat_result.marker_path
+        if termination_reason is None and self.config.stale_kill_threshold_seconds > 0 and handle.popen.returncode is None:
+            stale_marker = write_stale_marker(
+                session_log.parent,
+                reason="stale_session",
+                stale_seconds=self.config.stale_kill_threshold_seconds,
+                threshold=self.config.stale_kill_threshold_seconds,
+            )
+            termination_reason = "stale_session"
+        recovery = recover_session_log(session_log, backup_log)
+        lines = session_log.read_text(encoding="utf-8", errors="ignore").splitlines()
+        summary = parse_stream_progress_lines(lines)
+        merged_progress: dict[str, object] = summary.to_dict()
+        if self.config.progress_path is not None:
+            existing_progress = {}
+            if self.config.progress_path.is_file():
+                try:
+                    existing_progress = json.loads(self.config.progress_path.read_text(encoding="utf-8"))
+                except (OSError, json.JSONDecodeError):
+                    existing_progress = {}
+            merged_progress = _merged_progress(existing_progress, summary)
+            self.config.progress_path.write_text(json.dumps(merged_progress, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        final_summary = _summary_from_progress_dict(merged_progress, summary)
+        ended = time.time()
+        return AISessionResult(
+            command=command,
+            exit_code=handle.popen.returncode,
+            timed_out=timed_out,
+            termination_reason=termination_reason,
+            stale_marker=stale_marker,
+            fatal_error_code=final_summary.fatal_error_code,
+            progress_summary=final_summary,
+            session_log=session_log,
+            backup_log=backup_log,
+            log_recovery=recovery,
+            started_epoch=started,
+            ended_epoch=ended,
+        )

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

@@ -0,0 +1,71 @@
+"""Status updater and progress summary contracts."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .paths import RuntimePaths
+
+
+@dataclass(frozen=True)
+class StatusTarget:
+    """Plan and state files touched by a status updater."""
+
+    kind: str
+    plan_path: Path
+    state_dir: Path
+
+
+@dataclass(frozen=True)
+class StatusUpdateRequest:
+    """A requested status updater action for behavior porting."""
+
+    target: StatusTarget
+    action: str
+    item_id: str | None = None
+    session_status: str | None = None
+    metadata: Mapping[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ProgressSummary:
+    """Provider-neutral stream progress metadata used by session primitives."""
+
+    event_type_counts: Mapping[str, int] = field(default_factory=dict)
+    claude_session_id: str = ""
+    cb_session_id: str = ""
+    result_subtype: str = ""
+    stop_reason: str = ""
+    has_usage: bool = False
+    permission_denial_count: int = 0
+    permission_denials: tuple[str, ...] = ()
+    fatal_error_code: str = ""
+    terminal_result_text: str = ""
+    errors: tuple[str, ...] = ()
+
+    def to_dict(self) -> dict[str, object]:
+        """Return JSON-serializable progress metadata."""
+        return {
+            "event_type_counts": dict(self.event_type_counts),
+            "claude_session_id": self.claude_session_id,
+            "cb_session_id": self.cb_session_id,
+            "result_subtype": self.result_subtype,
+            "stop_reason": self.stop_reason,
+            "has_usage": self.has_usage,
+            "permission_denial_count": self.permission_denial_count,
+            "permission_denials": list(self.permission_denials),
+            "fatal_error_code": self.fatal_error_code,
+            "terminal_result_text": self.terminal_result_text,
+            "errors": list(self.errors),
+        }
+
+
+def default_status_targets(paths: RuntimePaths) -> dict[str, StatusTarget]:
+    """Return the canonical status targets for all pipeline families."""
+    return {
+        "feature": StatusTarget("feature", paths.feature_plan, paths.feature_state_dir),
+        "bugfix": StatusTarget("bugfix", paths.bugfix_plan, paths.bugfix_state_dir),
+        "refactor": StatusTarget("refactor", paths.refactor_plan, paths.refactor_state_dir),
+    }