pulse-coding-agent 0.1.0__py3-none-any.whl

pulse/edits.py

@@ -0,0 +1,65 @@
+"""Approval-gated file editing, independent from any user interface."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from difflib import unified_diff
+
+from pulse.sandbox import ProjectSandbox
+
+
+@dataclass(frozen=True)
+class EditProposal:
+    file_path: str
+    before_content: str | None
+    after_content: str
+    reason: str
+    unified_diff: str
+
+
+@dataclass(frozen=True)
+class EditResult:
+    proposal: EditProposal
+    applied: bool
+
+
+ApprovalHandler = Callable[[EditProposal], Awaitable[bool]]
+
+
+class EditWorkflow:
+    """Creates diffs first and mutates a project only after explicit approval."""
+
+    def __init__(self, sandbox: ProjectSandbox) -> None:
+        self.sandbox = sandbox
+
+    async def propose(self, file_path: str, content: str, reason: str) -> EditProposal:
+        before = self.sandbox.read_file_for_edit(file_path)
+        return EditProposal(
+            file_path=file_path,
+            before_content=before,
+            after_content=content,
+            reason=reason,
+            unified_diff="".join(
+                unified_diff(
+                    (before or "").splitlines(keepends=True),
+                    content.splitlines(keepends=True),
+                    fromfile=f"a/{file_path}",
+                    tofile=f"b/{file_path}",
+                )
+            ),
+        )
+
+    async def request_and_apply(
+        self, file_path: str, content: str, reason: str, approve: ApprovalHandler
+    ) -> EditResult:
+        proposal = await self.propose(file_path, content, reason)
+        if not await approve(proposal):
+            self.sandbox.record_rejected_edit(proposal.file_path, proposal.reason)
+            return EditResult(proposal=proposal, applied=False)
+
+        self.sandbox.apply_approved_edit(proposal.file_path, proposal.after_content, proposal.reason)
+        return EditResult(proposal=proposal, applied=True)
+
+    async def rollback_last(self) -> bool:
+        return self.sandbox.rollback_last_approved_edit()

pulse/episodic.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+from pulse.storage import migrate_database
+
+EPISODIC_SCHEMA_VERSION = 1
+
+
+@dataclass(frozen=True)
+class ExecutionTrace:
+    id: int
+    timestamp: str
+    prompt: str
+    error: str
+    resolution: str
+
+
+class EpisodicMemory:
+    """Manages execution trace storage (Prompt, Error, Resolution) in workspace SQLite database."""
+
+    def __init__(self, db_path: Path | None = None) -> None:
+        self.db_path = db_path or Path(".agent/episodic-memory.sqlite3")
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._init_db()
+
+    def _init_db(self) -> None:
+        def migration(conn: sqlite3.Connection, _current: int) -> None:
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS execution_traces (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    timestamp TEXT NOT NULL,
+                    prompt TEXT NOT NULL,
+                    error TEXT NOT NULL,
+                    resolution TEXT NOT NULL
+                )
+                """
+            )
+        migrate_database(self.db_path, EPISODIC_SCHEMA_VERSION, migration)
+
+    def log_trace(self, prompt: str, error: str, resolution: str) -> ExecutionTrace:
+        timestamp = datetime.now(UTC).isoformat()
+        with sqlite3.connect(self.db_path) as conn:
+            cursor = conn.cursor()
+            cursor.execute(
+                "INSERT INTO execution_traces (timestamp, prompt, error, resolution) VALUES (?, ?, ?, ?)",
+                (timestamp, prompt, error, resolution),
+            )
+            conn.commit()
+            trace_id = cursor.lastrowid or 0
+
+        return ExecutionTrace(
+            id=trace_id,
+            timestamp=timestamp,
+            prompt=prompt,
+            error=error,
+            resolution=resolution,
+        )
+
+    def search_similar_resolutions(self, query: str, limit: int = 5) -> list[ExecutionTrace]:
+        query_lower = f"%{query.lower()}%"
+        with sqlite3.connect(self.db_path) as conn:
+            cursor = conn.cursor()
+            cursor.execute(
+                """
+                SELECT id, timestamp, prompt, error, resolution
+                FROM execution_traces
+                WHERE LOWER(prompt) LIKE ? OR LOWER(error) LIKE ? OR LOWER(resolution) LIKE ?
+                ORDER BY id DESC
+                LIMIT ?
+                """,
+                (query_lower, query_lower, query_lower, limit),
+            )
+            rows = cursor.fetchall()
+
+        return [
+            ExecutionTrace(id=row[0], timestamp=row[1], prompt=row[2], error=row[3], resolution=row[4])
+            for row in rows
+        ]
+
+    def get_all_traces(self) -> list[ExecutionTrace]:
+        with sqlite3.connect(self.db_path) as conn:
+            cursor = conn.cursor()
+            cursor.execute("SELECT id, timestamp, prompt, error, resolution FROM execution_traces ORDER BY id ASC")
+            rows = cursor.fetchall()
+        return [
+            ExecutionTrace(id=row[0], timestamp=row[1], prompt=row[2], error=row[3], resolution=row[4])
+            for row in rows
+        ]

pulse/eval/__init__.py

@@ -0,0 +1,8 @@
+"""Evaluation utilities for Pulse.
+Provides:
+- PatchVerifier: Apply candidate diffs and evaluate test outcomes.
+- TrajectoryLogger: Record agent action trajectories.
+"""
+
+from .trajectory_logger import TrajectoryLogger, TrajectoryStep  # noqa: F401
+from .verifier import PatchVerifier  # noqa: F401

pulse/eval/trajectory_logger.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import json
+import uuid
+from collections.abc import Mapping, Sequence
+from dataclasses import asdict, dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(slots=True)
+class TrajectoryStep:
+    """A single recorded step of an agent run."""
+
+    timestamp: str = field(default_factory=lambda: datetime.now(UTC).isoformat())
+    prompt: str | None = None
+    tool_name: str | None = None
+    tool_args: Mapping[str, Any] | None = None
+    reasoning: str | None = None
+    token_cost: int | None = None
+    test_log: str | None = None
+    result: str | None = None
+
+class TrajectoryLogger:
+    """Collects and persists a sequence of :class:`TrajectoryStep` objects.
+    Stored under ``.agent/trajectories/<task_id>.json``.
+    """
+
+    def __init__(self, workspace: Path, task_id: str | None = None) -> None:
+        self.workspace = workspace.resolve()
+        self.task_id = task_id or uuid.uuid4().hex
+        self._steps: list[TrajectoryStep] = []
+        self._base = self.workspace / ".agent" / "trajectories"
+        self._base.mkdir(parents=True, exist_ok=True)
+
+    # ------------------------------------------------------------------ API
+    def add_step(
+        self,
+        *,
+        prompt: str | None = None,
+        tool_name: str | None = None,
+        tool_args: Mapping[str, Any] | None = None,
+        reasoning: str | None = None,
+        token_cost: int | None = None,
+        test_log: str | None = None,
+        result: str | None = None,
+    ) -> None:
+        """Append a new step to the internal buffer."""
+        step = TrajectoryStep(
+            prompt=prompt,
+            tool_name=tool_name,
+            tool_args=tool_args,
+            reasoning=reasoning,
+            token_cost=token_cost,
+            test_log=test_log,
+            result=result,
+        )
+        self._steps.append(step)
+
+    def dump(self) -> Path:
+        """Write the buffered steps to ``.agent/trajectories/<task_id>.json``.
+        Returns the path to the written file.
+        """
+        out_path = self._base / f"{self.task_id}.json"
+        payload = {
+            "schema_version": 1,
+            "task_id": self.task_id,
+            "steps": [asdict(step) for step in self._steps],
+        }
+        out_path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+        return out_path
+
+    def load(self) -> Sequence[TrajectoryStep]:
+        """Load a previously persisted trajectory (if it exists) and replace the buffer.
+        Returns the loaded list of steps.
+        """
+        path = self._base / f"{self.task_id}.json"
+        if not path.is_file():
+            self._steps = []
+            return []
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        raw: list[dict[str, Any]] = payload if isinstance(payload, list) else payload["steps"]
+        self._steps = [TrajectoryStep(**item) for item in raw]
+        return self._steps
+
+    # ------------------------------------------------------------------ Helpers
+    @property
+    def steps(self) -> Sequence[TrajectoryStep]:
+        """Read‑only view of the current steps buffer."""
+        return tuple(self._steps)

pulse/eval/verifier.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, TypedDict
+
+from pulse.subprocesses import isolated_process_kwargs
+
+TestResult = Literal["pass", "fail"]
+
+class PatchVerificationMetrics(TypedDict):
+    """Outcome metrics for a candidate fix."""
+    issue_description: str
+    patch: str
+    initial_test_result: TestResult
+    post_apply_test_result: TestResult
+    fail_to_pass: bool
+    pass_to_pass: bool
+    pytest_stdout: str
+    pytest_stderr: str
+
+@dataclass(slots=True)
+class PatchVerifier:
+    """Applies a diff to a copy of the repository and evaluates test outcomes."""
+
+    workspace: Path
+    """Root of the original Pulse project."""
+
+    def _run_pytest(self, directory: Path) -> tuple[int, str, str]:
+        """Execute ``pytest`` in *directory* and return (returncode, stdout, stderr)."""
+        try:
+            proc = subprocess.run(
+                [sys.executable, "-m", "pytest", "-p", "no:cacheprovider"],
+                cwd=directory,
+                capture_output=True,
+                text=True,
+                timeout=120,
+                check=False,
+                env={**os.environ, "PYTHONDONTWRITEBYTECODE": "1"},
+                **isolated_process_kwargs(),
+            )
+            return proc.returncode, proc.stdout, proc.stderr
+        except subprocess.TimeoutExpired as exc:
+            return -1, "", f"Timeout: {exc}"
+
+    def _apply_patch(self, target_dir: Path, patch_text: str) -> tuple[bool, str]:
+        """Validate and apply a unified diff without allowing paths outside the copy."""
+        if not patch_text:
+            return False, "Patch is empty."
+        try:
+            normalized_patch = patch_text if patch_text.endswith("\n") else patch_text + "\n"
+            for mode in ("--check", "--apply"):
+                proc = subprocess.run(
+                    ["git", "apply", mode, "--whitespace=nowarn", "-"],
+                    cwd=target_dir,
+                    input=normalized_patch,
+                    capture_output=True,
+                    text=True,
+                    timeout=30,
+                    check=False,
+                    **isolated_process_kwargs(),
+                )
+                if proc.returncode != 0:
+                    detail = proc.stderr.strip() or proc.stdout.strip() or "git apply failed"
+                    return False, detail
+            return True, ""
+        except (OSError, subprocess.TimeoutExpired) as exc:
+            return False, f"Patch application failed: {exc}"
+
+    def verify(self, issue_description: str, patch: str) -> PatchVerificationMetrics:
+        """Run the verification cycle and return detailed metrics.
+        Steps:
+        1. Run pytest on the original workspace (baseline).
+        2. Copy the workspace to a temporary isolated directory.
+        3. Apply the supplied *patch* in the temporary copy.
+        4. Re‑run pytest on the patched copy.
+        5. Compute pass/fail transitions and return the metrics dict.
+        """
+        # Baseline run
+        init_rc, _init_out, _init_err = self._run_pytest(self.workspace)
+        initial_result: TestResult = "pass" if init_rc == 0 else "fail"
+
+        # Isolated copy and patch application
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            tmp_path = Path(tmp_dir)
+            ignored = {
+                ".git",
+                ".mypy_cache",
+                ".pytest_cache",
+                ".ruff_cache",
+                ".venv",
+                "__pycache__",
+                "build",
+                "dist",
+                "venv",
+            }
+            for item in self.workspace.iterdir():
+                if item.name in ignored:
+                    continue
+                dest = tmp_path / item.name
+                if item.is_dir():
+                    shutil.copytree(
+                        item,
+                        dest,
+                        dirs_exist_ok=True,
+                        ignore=shutil.ignore_patterns(*ignored),
+                    )
+                else:
+                    shutil.copy2(item, dest)
+
+            applied, apply_error = self._apply_patch(tmp_path, patch)
+            if applied:
+                post_rc, post_out, post_err = self._run_pytest(tmp_path)
+            else:
+                post_rc, post_out, post_err = -1, "", apply_error
+
+        post_result: TestResult = "pass" if post_rc == 0 else "fail"
+
+        return {
+            "issue_description": issue_description,
+            "patch": patch,
+            "initial_test_result": initial_result,
+            "post_apply_test_result": post_result,
+            "fail_to_pass": initial_result == "fail" and post_result == "pass",
+            "pass_to_pass": initial_result == "pass" and post_result == "pass",
+            "pytest_stdout": post_out,
+            "pytest_stderr": post_err,
+        }

pulse/execution/__init__.py

@@ -0,0 +1,5 @@
+"""Execution adapters that bind durable tasks to isolated backends."""
+
+from pulse.execution.remote_task import RemoteTaskExecutor
+
+__all__ = ["RemoteTaskExecutor"]

pulse/execution/remote_task.py

@@ -0,0 +1,76 @@
+"""Fenced bridge between durable tasks and the remote sandbox."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from pulse.sandbox.api import Sandbox
+from pulse.sandbox.process import ProcessResult
+from pulse.task_manager import Task, TaskManager
+
+
+@dataclass(slots=True)
+class RemoteTaskExecutor:
+    """Submit one task attempt to a remote sandbox using its durable ID.
+
+    This adapter is deliberately outside both ``TaskManager`` and the sandbox:
+    the task layer owns fencing and recovery while the sandbox owns execution
+    policy.  It is the sole bridge responsible for carrying the fenced
+    ``remote_execution_id`` across that boundary.
+    """
+
+    task_manager: TaskManager
+    sandbox: Sandbox
+
+    async def execute(
+        self,
+        task_id: str,
+        command: str | list[str],
+        *,
+        cwd: Path | str | None = None,
+        env: dict[str, str] | None = None,
+    ) -> Task:
+        await self.sandbox.initialize()
+        if getattr(self.sandbox.backend, "name", None) != "remote":
+            raise RuntimeError(
+                "RemoteTaskExecutor requires a configured remote sandbox backend."
+            )
+
+        task = await self.task_manager.start_task(task_id)
+        execution_id = await self.task_manager.remote_execution_id_for_task(task.id)
+        try:
+            result = await self.sandbox.execute_command(
+                command,
+                cwd=cwd,
+                env=env,
+                execution_id=execution_id,
+            )
+        except Exception as err:  # noqa: BLE001 - persists a recoverable task failure
+            return await self.task_manager.fail_task(task.id, str(err))
+
+        if self._succeeded(result):
+            return await self.task_manager.complete_task(
+                task.id, json.dumps(self._result_payload(result), sort_keys=True)
+            )
+        return await self.task_manager.fail_task(
+            task.id,
+            result.stderr or f"Remote command exited with code {result.exit_code}.",
+        )
+
+    @staticmethod
+    def _succeeded(result: ProcessResult) -> bool:
+        return result.exit_code == 0 and not result.timed_out
+
+    @staticmethod
+    def _result_payload(result: ProcessResult) -> dict[str, Any]:
+        return {
+            "exit_code": result.exit_code,
+            "stdout": result.stdout,
+            "stderr": result.stderr,
+            "duration_ms": result.duration_ms,
+            "timed_out": result.timed_out,
+            "termination_reason": result.termination_reason,
+        }

pulse/git.py

@@ -0,0 +1,162 @@
+"""Async Git inspection and commit guidance, independent of Pulse interfaces."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from pulse.subprocesses import (
+    isolated_process_kwargs,
+    isolated_subprocess_environment,
+    terminate_process,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class GitChange:
+    path: str
+    index_status: str
+    worktree_status: str
+
+
+@dataclass(frozen=True, slots=True)
+class GitStatus:
+    is_repository: bool
+    branch: str | None = None
+    head: str | None = None
+    changes: tuple[GitChange, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class DiffAnalysis:
+    files_changed: int
+    additions: int
+    deletions: int
+    files: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class GitInsight:
+    status: GitStatus
+    diff: DiffAnalysis
+    commit_suggestion: str | None
+
+
+GitRunner = Callable[[tuple[str, ...], Path], Awaitable[tuple[int, str, str]]]
+
+
+class GitIntelligence:
+    """Read-only Git state, diff analysis, and conventional commit suggestions."""
+
+    def __init__(self, workspace: Path, *, runner: GitRunner | None = None) -> None:
+        self.workspace = workspace.resolve()
+        self._runner = runner or self._run_git
+
+    async def status(self) -> GitStatus:
+        code, output, _ = await self._runner(("rev-parse", "--is-inside-work-tree"), self.workspace)
+        if code != 0 or output.strip() != "true":
+            return GitStatus(False)
+        _, branch, _ = await self._runner(("branch", "--show-current"), self.workspace)
+        _, head, _ = await self._runner(("rev-parse", "--short", "HEAD"), self.workspace)
+        _, porcelain, _ = await self._runner(("status", "--porcelain=v1"), self.workspace)
+        return GitStatus(True, branch.strip() or None, head.strip() or None, self._parse_status(porcelain))
+
+    async def analyze_diff(self) -> DiffAnalysis:
+        status = await self.status()
+        if not status.is_repository:
+            return DiffAnalysis(0, 0, 0)
+        _, unstaged, _ = await self._runner(
+            ("diff", "--no-ext-diff", "--no-textconv", "--numstat"), self.workspace
+        )
+        _, staged, _ = await self._runner(
+            ("diff", "--cached", "--no-ext-diff", "--no-textconv", "--numstat"),
+            self.workspace,
+        )
+        additions = deletions = 0
+        files = {change.path for change in status.changes}
+        for line in f"{unstaged}\n{staged}".splitlines():
+            parts = line.split("\t", 2)
+            if len(parts) != 3:
+                continue
+            added, removed, path = parts
+            additions += int(added) if added.isdigit() else 0
+            deletions += int(removed) if removed.isdigit() else 0
+            files.add(path)
+        return DiffAnalysis(len(files), additions, deletions, tuple(sorted(files)))
+
+    async def inspect(self) -> GitInsight:
+        """Return branch, working-tree changes, diff totals, and a commit idea."""
+        status = await self.status()
+        if not status.is_repository:
+            return GitInsight(status, DiffAnalysis(0, 0, 0), None)
+        # Reuse the status we already collected while keeping diff collection
+        # independent and safe for callers that only need one of the operations.
+        _, unstaged, _ = await self._runner(
+            ("diff", "--no-ext-diff", "--no-textconv", "--numstat"), self.workspace
+        )
+        _, staged, _ = await self._runner(
+            ("diff", "--cached", "--no-ext-diff", "--no-textconv", "--numstat"),
+            self.workspace,
+        )
+        additions = deletions = 0
+        files = {change.path for change in status.changes}
+        for line in f"{unstaged}\n{staged}".splitlines():
+            parts = line.split("\t", 2)
+            if len(parts) == 3:
+                additions += int(parts[0]) if parts[0].isdigit() else 0
+                deletions += int(parts[1]) if parts[1].isdigit() else 0
+                files.add(parts[2])
+        diff = DiffAnalysis(len(files), additions, deletions, tuple(sorted(files)))
+        return GitInsight(status, diff, self.suggest_commit(status, diff))
+
+    @staticmethod
+    def suggest_commit(status: GitStatus, diff: DiffAnalysis) -> str | None:
+        if not status.is_repository or not diff.files:
+            return None
+        paths = diff.files
+        if all(path.lower().endswith((".md", ".rst")) or "docs/" in path.lower() for path in paths):
+            kind = "docs"
+        elif all("test" in Path(path).name.lower() for path in paths):
+            kind = "test"
+        elif any(change.index_status == "A" or change.worktree_status == "?" for change in status.changes):
+            kind = "feat"
+        else:
+            kind = "chore"
+        subject = paths[0] if len(paths) == 1 else f"{len(paths)} files"
+        return f"{kind}: update {subject}"
+
+    @staticmethod
+    def _parse_status(output: str) -> tuple[GitChange, ...]:
+        changes: list[GitChange] = []
+        for line in output.splitlines():
+            if len(line) < 4:
+                continue
+            changes.append(GitChange(line[3:], line[0], line[1]))
+        return tuple(changes)
+
+    @staticmethod
+    async def _run_git(arguments: tuple[str, ...], workspace: Path) -> tuple[int, str, str]:
+        process: asyncio.subprocess.Process | None = None
+        try:
+            process = await asyncio.create_subprocess_exec(
+                "git", *arguments, cwd=workspace, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE,
+                env=isolated_subprocess_environment(
+                    {
+                        "GIT_CONFIG_NOSYSTEM": "1",
+                        "GIT_CONFIG_GLOBAL": str(Path(os.devnull)),
+                        "GIT_ATTR_NOSYSTEM": "1",
+                    }
+                ),
+                **isolated_process_kwargs(),
+            )
+        except OSError as error:
+            return 127, "", str(error)
+        try:
+            stdout, stderr = await process.communicate()
+        except asyncio.CancelledError:
+            await terminate_process(process)
+            raise
+        return process.returncode, stdout.decode(errors="replace"), stderr.decode(errors="replace")