fuzzprep 0.1.0__py3-none-any.whl

fuzzprep/core/agent_stream.py

@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+
+AgentActivityKind = Literal[
+    "model_text", "status", "file_read", "file_edit", "command_run", "tool_result", "raw_fallback"
+]
+
+
+@dataclass
+class AgentActivityEvent:
+    kind: AgentActivityKind
+    text: str
+
+
+@dataclass
+class AgentStreamResult:
+    """One agent invocation's output, split into two channels.
+
+    `combined_text` is the whole rendered transcript, including tool results and narration
+    lines. It is what gets persisted for a human to read.
+
+    `model_text` is only what the model itself wrote: Claude `text` blocks and Codex
+    `agent_message` items. Match on this when looking for a marker the model was told to
+    print, such as `ACTION REQUIRED` — searching the whole transcript trips on any file that
+    merely quotes it. Thinking blocks are excluded too, so an agent weighing whether to print
+    a marker is not read as having printed it.
+    """
+
+    combined_text: str
+    exit_code: int
+    duration_seconds: float
+    cost_usd: float | None = None
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    model_text: str = ""
+
+
+_CLAUDE_READ_TOOLS = {"Read"}
+_CLAUDE_EDIT_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit"}
+_CLAUDE_COMMAND_TOOLS = {"Bash"}
+
+
+def _raw_fallback(line: str) -> list[AgentActivityEvent]:
+    return [AgentActivityEvent("raw_fallback", line.rstrip("\n"))]
+
+
+def _claude_tool_event(name: str, tool_input: dict[str, Any]) -> AgentActivityEvent:
+    if name in _CLAUDE_READ_TOOLS:
+        return AgentActivityEvent("file_read", f"Reading {tool_input.get('file_path', '?')}")
+    if name in _CLAUDE_EDIT_TOOLS:
+        return AgentActivityEvent("file_edit", f"Editing {tool_input.get('file_path', '?')}")
+    if name in _CLAUDE_COMMAND_TOOLS:
+        return AgentActivityEvent("command_run", f"Running: {tool_input.get('command', '?')}")
+    return AgentActivityEvent("status", f"Using tool {name}")
+
+
+def _tool_result_text(content: Any) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        return "\n".join(
+            part.get("text", "")
+            for part in content
+            if isinstance(part, dict) and part.get("type") == "text"
+        )
+    return json.dumps(content)
+
+
+def _claude_content_block_event(block: dict[str, Any]) -> AgentActivityEvent | None:
+    block_type = block.get("type")
+    if block_type == "text":
+        return AgentActivityEvent("model_text", block.get("text", ""))
+    if block_type == "thinking":
+        thinking = block.get("thinking") or ""
+        return AgentActivityEvent("status", f"Thinking: {thinking}") if thinking else None
+    if block_type == "tool_use":
+        return _claude_tool_event(block.get("name", ""), block.get("input", {}))
+    if block_type == "tool_result":
+        return AgentActivityEvent("tool_result", _tool_result_text(block.get("content")))
+    return None
+
+
+def _parse_claude_line(line: str) -> list[AgentActivityEvent]:
+    """Parse one line of `claude --output-format stream-json` output.
+
+    New top-level event types appear over time, so they are not enumerated. A well-formed JSON
+    object with a `type` string is a legitimate event this simply renders no narration for.
+    `raw_fallback` is reserved for a line that doesn't look like a structured event at all, so
+    garbled input stays visible without every future event type dumping raw JSON.
+    """
+    try:
+        data = json.loads(line)
+    except json.JSONDecodeError:
+        return _raw_fallback(line)
+    if not isinstance(data, dict) or not isinstance(data.get("type"), str):
+        return _raw_fallback(line)
+    if data["type"] not in ("assistant", "user"):
+        return []
+    content = data.get("message", {}).get("content", [])
+    if not isinstance(content, list):
+        return []
+    events: list[AgentActivityEvent] = []
+    for block in content:
+        if not isinstance(block, dict):
+            continue
+        event = _claude_content_block_event(block)
+        if event is not None:
+            events.append(event)
+    return events
+
+
+def _codex_item_event(item: dict[str, Any]) -> AgentActivityEvent | None:
+    item_type = item.get("type")
+    if item_type == "command_execution":
+        return AgentActivityEvent("command_run", f"Running: {item.get('command', '?')}")
+    if item_type == "file_change":
+        return AgentActivityEvent("file_edit", f"Editing {item.get('path', '?')}")
+    if item_type == "agent_message":
+        # Codex's equivalent of a Claude text content block: the model's response text.
+        return AgentActivityEvent("model_text", item.get("text", ""))
+    if item_type == "reasoning":
+        # Codex's equivalent of Claude's "thinking" block.
+        text = item.get("text") or ""
+        return AgentActivityEvent("status", f"Thinking: {text}") if text else None
+    if item_type == "error":
+        return AgentActivityEvent("status", f"Warning: {item.get('message', '?')}")
+    return None
+
+
+def _parse_codex_line(line: str) -> list[AgentActivityEvent]:
+    """Parse one line of `codex exec --json` output.
+
+    Same silent-skip vs `raw_fallback` distinction as `_parse_claude_line`.
+    """
+    try:
+        data = json.loads(line)
+    except json.JSONDecodeError:
+        return _raw_fallback(line)
+    if not isinstance(data, dict) or not isinstance(data.get("type"), str):
+        return _raw_fallback(line)
+    if data["type"] not in ("item.started", "item.updated", "item.completed"):
+        return []
+    item = data.get("item")
+    if not isinstance(item, dict):
+        return []
+    event = _codex_item_event(item)
+    return [event] if event is not None else []
+
+
+_LINE_PARSERS: dict[str, Callable[[str], list[AgentActivityEvent]]] = {
+    "claude": _parse_claude_line,
+    "codex": _parse_codex_line,
+}
+
+
+def _claude_result_cost(line: str) -> tuple[float | None, int | None, int | None]:
+    try:
+        data = json.loads(line)
+    except json.JSONDecodeError:
+        return None, None, None
+    if not isinstance(data, dict) or data.get("type") != "result":
+        return None, None, None
+    cost = data.get("total_cost_usd")
+    # An error result -- the shape a 529 leaves behind -- can omit `usage` entirely, and this
+    # runs inside the stdout loop, where an AttributeError would abort the whole invocation.
+    usage = data.get("usage")
+    if not isinstance(usage, dict):
+        usage = {}
+    input_tokens = usage.get("input_tokens")
+    output_tokens = usage.get("output_tokens")
+    return (
+        cost if isinstance(cost, float) else None,
+        input_tokens if isinstance(input_tokens, int) else None,
+        output_tokens if isinstance(output_tokens, int) else None,
+    )
+
+
+def _codex_result_cost(line: str) -> tuple[None, int | None, int | None]:
+    try:
+        data = json.loads(line)
+    except json.JSONDecodeError:
+        return None, None, None
+    if not isinstance(data, dict) or data.get("type") != "turn.completed":
+        return None, None, None
+    usage = data.get("usage")
+    if not isinstance(usage, dict):
+        return None, None, None
+    # Codex reports tokens but no cost.
+    return None, usage.get("input_tokens"), usage.get("output_tokens")
+
+
+def _extract_stats(tool: str, line: str) -> tuple[float | None, int | None, int | None]:
+    if tool == "claude":
+        return _claude_result_cost(line)
+    return _codex_result_cost(line)
+
+
+@dataclass
+class _StreamAccumulator:
+    cost_usd: float | None = None
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+
+
+def _apply_line_stats(acc: _StreamAccumulator, tool: str, line: str) -> None:
+    """Update the running stats accumulator from one stdout line, last-value-wins."""
+    cost, input_tokens, output_tokens = _extract_stats(tool, line)
+    if cost is not None:
+        acc.cost_usd = cost
+    if input_tokens is not None:
+        acc.input_tokens = input_tokens
+    if output_tokens is not None:
+        acc.output_tokens = output_tokens
+
+
+def run_agent_streaming(
+    command: list[str], cwd: Path, timeout: int, tool: str
+) -> AgentStreamResult:
+    """Run an agent CLI, rendering its structured event stream as readable lines.
+
+    Mirrors run_command_streaming's structure, but parses each line as a backend-specific
+    event instead of treating it as opaque text.
+    """
+    if tool not in _LINE_PARSERS:
+        raise ValueError(f"unknown agent tool: {tool!r}")
+    parse_line = _LINE_PARSERS[tool]
+
+    start = time.monotonic()
+    texts: list[str] = []
+    model_texts: list[str] = []
+    acc = _StreamAccumulator()
+    proc = subprocess.Popen(
+        command,
+        cwd=cwd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        bufsize=1,
+    )
+    assert proc.stdout is not None
+    try:
+        for line in proc.stdout:
+            for event in parse_line(line):
+                print(event.text, flush=True)
+                texts.append(event.text)
+                if event.kind == "model_text":
+                    model_texts.append(event.text)
+            _apply_line_stats(acc, tool, line)
+        proc.wait(timeout=timeout)
+        exit_code = proc.returncode
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        proc.wait()
+        exit_code = -1
+
+    return AgentStreamResult(
+        combined_text="\n".join(texts),
+        exit_code=exit_code,
+        duration_seconds=time.monotonic() - start,
+        cost_usd=acc.cost_usd,
+        input_tokens=acc.input_tokens,
+        output_tokens=acc.output_tokens,
+        model_text="\n".join(model_texts),
+    )
+
+
+@dataclass
+class AgentRunSummary:
+    backend: str
+    outcome: str
+    duration_seconds: float
+    cost_usd: float | None
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+
+
+def format_agent_summary(summary: AgentRunSummary) -> str:
+    """Render the fixed-format '=== Agent Run Summary ===' trailer block."""
+    if summary.cost_usd is not None:
+        stats_line = f"cost: ${summary.cost_usd:.4f}"
+    elif summary.input_tokens is not None and summary.output_tokens is not None:
+        stats_line = f"tokens: input={summary.input_tokens} output={summary.output_tokens}"
+    else:
+        stats_line = "cost: unavailable"
+
+    return (
+        "=== Agent Run Summary ===\n"
+        f"backend: {summary.backend}\n"
+        f"outcome: {summary.outcome}\n"
+        f"duration: {summary.duration_seconds:.1f}s\n"
+        f"{stats_line}\n"
+    )
+
+
+def write_agent_report(path: Path, combined_text: str, summary: AgentRunSummary) -> None:
+    """Persist an invocation's transcript and time/cost summary to a report file."""
+    path.write_text(f"{combined_text}\n{format_agent_summary(summary)}")

fuzzprep/core/files.py

@@ -0,0 +1,35 @@
+"""Writing files that are meant to be run."""
+
+from __future__ import annotations
+
+import shutil
+import stat
+from pathlib import Path
+
+_EXECUTABLE_BITS = stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH
+
+
+def write_executable(path: Path, text: str) -> Path:
+    """Write text to path and make it executable, returning path.
+
+    Every generated shell script goes through here. FuzzPrep runs them, repair agents run
+    them, and users run them, so one written without the executable bit is broken three ways.
+    """
+    path.write_text(text)
+    return make_executable(path)
+
+
+def copy_executable(source: Path, destination: Path) -> Path:
+    """Copy source to destination and make it executable, returning destination.
+
+    For publishing a validated script verbatim rather than regenerating it, so any repair an
+    agent applied survives into the output.
+    """
+    shutil.copy2(source, destination)
+    return make_executable(destination)
+
+
+def make_executable(path: Path) -> Path:
+    """Add the executable bits to an existing file, returning path."""
+    path.chmod(path.stat().st_mode | _EXECUTABLE_BITS)
+    return path

fuzzprep/core/paths.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+_STATE_DIR_NAME = ".fuzzprep"
+
+
+def default_state_dir() -> Path:
+    """Return the repo-local FuzzPrep state directory path."""
+    return Path(_STATE_DIR_NAME)
+
+
+def project_dir(state_dir: Path, project_name: str) -> Path:
+    """Return the project workspace directory (.fuzzprep/<project>/)."""
+    return state_dir / project_name
+
+
+def project_state_file(state_dir: Path, project_name: str) -> Path:
+    """Return the per-project persistent state file (.fuzzprep/<project>/state.json)."""
+    return state_dir / project_name / "state.json"
+
+
+def project_logs_dir(state_dir: Path, project_name: str) -> Path:
+    """Return the per-phase log directory (.fuzzprep/<project>/logs/)."""
+    return state_dir / project_name / "logs"

fuzzprep/core/reporting.py

@@ -0,0 +1,218 @@
+"""Phase reporting and failure diagnostics for the `generate` console output.
+
+`Phase`/`PhaseExecution` track which pipeline stage is running and how it ended.
+`PhaseReporter` brackets a phase's output with start/end banners. `FailureDiagnostic`
+turns a phase's failure into a short, located summary.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from types import TracebackType
+from typing import Literal
+
+_BANNER_WIDTH = 70
+_DEFAULT_MESSAGE_LINES = 2
+
+
+class Phase(Enum):
+    """Ordered, fixed set of pipeline stages a `generate` run passes through."""
+
+    INGESTION = "ingestion"
+    STATIC_ANALYSIS = "static_analysis"
+    DETERMINISTIC_LIBRARY_BUILD = "deterministic_library_build"
+    AGENT_LIBRARY_REPAIR = "agent_library_repair"
+    HARNESS_COMPILE_PROBE = "harness_compile_probe"
+    AGENT_HARNESS_REPAIR = "agent_harness_repair"
+    DOCKERFILE_VERIFICATION = "dockerfile_verification"
+    OUTPUT_GENERATION = "output_generation"
+
+
+_PHASE_LABELS: dict[Phase, str] = {
+    Phase.INGESTION: "Repository ingestion",
+    Phase.STATIC_ANALYSIS: "Static analysis",
+    Phase.DETERMINISTIC_LIBRARY_BUILD: "Deterministic library build",
+    Phase.AGENT_LIBRARY_REPAIR: "Agent-assisted library repair",
+    Phase.HARNESS_COMPILE_PROBE: "Harness compile probe",
+    Phase.AGENT_HARNESS_REPAIR: "Agent-assisted harness repair",
+    Phase.DOCKERFILE_VERIFICATION: "From-scratch Dockerfile verification",
+    Phase.OUTPUT_GENERATION: "Output generation",
+}
+
+_AGENT_PHASES = frozenset({Phase.AGENT_LIBRARY_REPAIR, Phase.AGENT_HARNESS_REPAIR})
+
+
+def phase_label(phase: Phase) -> str:
+    """Return the console label for phase."""
+    return _PHASE_LABELS[phase]
+
+
+def is_agent_phase(phase: Phase) -> bool:
+    """Whether phase is one of the agent-assisted repair phases."""
+    return phase in _AGENT_PHASES
+
+
+PhaseStatus = Literal["running", "succeeded", "failed"]
+
+
+@dataclass
+class PhaseExecution:
+    """One instance per phase actually run in a given `generate` invocation."""
+
+    phase: Phase
+    status: PhaseStatus = "running"
+    started_at: float = 0.0
+    ended_at: float | None = None
+
+    def mark_succeeded(self) -> None:
+        self._transition("succeeded")
+
+    def mark_failed(self) -> None:
+        self._transition("failed")
+
+    def _transition(self, status: PhaseStatus) -> None:
+        if self.status != "running":
+            raise ValueError(f"cannot transition a {self.status!r} PhaseExecution to {status!r}")
+        self.status = status
+        self.ended_at = time.monotonic()
+
+
+@dataclass
+class FailureDiagnostic:
+    """Shown to the user when a phase fails."""
+
+    phase: Phase
+    step: str
+    message: str
+    origin: Literal["deterministic", "agent"]
+    log_path: Path | None = None
+    exit_code: int | None = None
+
+
+def summarize_message(text: str, *, max_lines: int = _DEFAULT_MESSAGE_LINES) -> str:
+    """Collapse raw command output down to a short, human-readable diagnostic message:
+    the last max_lines non-blank lines, which is usually where the actual error is."""
+    non_blank = [line for line in text.splitlines() if line.strip()]
+    if not non_blank:
+        return "(no output captured)"
+    return "\n".join(non_blank[-max_lines:])
+
+
+def build_diagnostic(  # noqa: PLR0913 -- one param per FailureDiagnostic field
+    phase: Phase,
+    *,
+    step: str,
+    message: str,
+    origin: Literal["deterministic", "agent"],
+    log_path: Path | None = None,
+    exit_code: int | None = None,
+) -> FailureDiagnostic:
+    """Construct a `FailureDiagnostic` — the single place these are assembled, so every
+    call site produces the same shape."""
+    return FailureDiagnostic(
+        phase=phase,
+        step=step,
+        message=message,
+        origin=origin,
+        log_path=log_path,
+        exit_code=exit_code,
+    )
+
+
+def _banner_line(phase: Phase, marker: str) -> str:
+    fill = "#" if is_agent_phase(phase) else "="
+    prefix = "AGENT: " if is_agent_phase(phase) else ""
+    core = f" {prefix}{phase_label(phase)} [{marker}] "
+    pad = max(3, (_BANNER_WIDTH - len(core)) // 2)
+    return f"{fill * pad}{core}{fill * pad}"
+
+
+def format_phase_start_banner(phase: Phase) -> str:
+    """The line printed before a phase's own output begins."""
+    return _banner_line(phase, "START")
+
+
+def format_phase_end_banner(phase: Phase, status: Literal["succeeded", "failed"]) -> str:
+    """The line printed once a phase concludes."""
+    return _banner_line(phase, status.upper())
+
+
+def format_diagnostic(
+    diagnostic: FailureDiagnostic, *, debug: bool = False, raw_output: str | None = None
+) -> str:
+    """Render a `FailureDiagnostic` for the console.
+
+    When debug is set and raw_output is non-empty, the failing step's full raw output is
+    inlined here as well, whether or not it also streamed live.
+    """
+    origin_text = (
+        "agent repair attempt failed" if diagnostic.origin == "agent" else "build step failed"
+    )
+    lines = [
+        f"--- FAILURE: {phase_label(diagnostic.phase)} ---",
+        f"Step: {diagnostic.step}",
+        f"Message: {diagnostic.message}",
+        f"Origin: {origin_text}",
+    ]
+    if diagnostic.exit_code is not None:
+        lines.append(f"Exit code: {diagnostic.exit_code}")
+    log_text = str(diagnostic.log_path) if diagnostic.log_path is not None else "(not captured)"
+    lines.append(f"Full output: {log_text}")
+    if debug and raw_output:
+        lines.append("--- Full raw output (--log-level debug) ---")
+        lines.append(raw_output)
+        lines.append("--- end raw output ---")
+    return "\n".join(lines)
+
+
+def format_startup_failure(message: str) -> str:
+    """A failure before any Phase has started still needs an actionable message."""
+    return f"--- STARTUP FAILURE ---\n{message}"
+
+
+class PhaseReporter:
+    """Brackets one phase's console output with a start/end banner.
+
+    Use as a context manager::
+
+        with PhaseReporter(Phase.DETERMINISTIC_LIBRARY_BUILD) as reporter:
+            result = do_the_thing()
+        if result.succeeded:
+            reporter.succeed()
+        else:
+            reporter.fail()
+
+    If the `with` block raises before `.succeed()`/`.fail()` is called, `__exit__`
+    marks the phase failed and prints the end banner automatically, without
+    swallowing the exception — so callers that fail via exception don't have to
+    remember to call `.fail()` themselves.
+    """
+
+    def __init__(self, phase: Phase) -> None:
+        self.phase = phase
+        self.execution = PhaseExecution(phase=phase, started_at=time.monotonic())
+
+    def __enter__(self) -> PhaseReporter:
+        print(format_phase_start_banner(self.phase))
+        return self
+
+    def succeed(self) -> None:
+        self.execution.mark_succeeded()
+        print(format_phase_end_banner(self.phase, "succeeded"))
+
+    def fail(self) -> None:
+        self.execution.mark_failed()
+        print(format_phase_end_banner(self.phase, "failed"))
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> Literal[False]:
+        if exc_type is not None and self.execution.status == "running":
+            self.fail()
+        return False