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

pulse/memory.py

@@ -0,0 +1,212 @@
+"""SQLite-backed long-term project memory, independent of Pulse interfaces."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+import sqlite3
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Protocol
+
+from pulse.sandbox.secrets import SecretScrubber
+from pulse.storage import migrate_database
+
+MEMORY_SCHEMA_VERSION = 1
+
+
+@dataclass(frozen=True, slots=True)
+class MemoryEntry:
+    id: int
+    category: str
+    content: str
+    tags: tuple[str, ...]
+    created_at: str
+
+
+class RequestWithMessage(Protocol):
+    message: str
+
+
+class LongTermMemory:
+    """Small async façade over a workspace-local SQLite memory database."""
+
+    def __init__(
+        self,
+        workspace: Path,
+        database_path: Path | None = None,
+        secrets: list[str] | None = None,
+    ) -> None:
+        self.workspace = workspace.resolve()
+        self.database_path = database_path or self.workspace / ".agent" / "pulse-memory.sqlite3"
+        self._lock = asyncio.Lock()
+        self._scrubber = SecretScrubber(secrets)
+        migrate_database(self.database_path, MEMORY_SCHEMA_VERSION, self._migrate_schema)
+
+    @staticmethod
+    def _migrate_schema(connection: sqlite3.Connection, _current: int) -> None:
+        connection.execute(
+            "CREATE TABLE IF NOT EXISTS memories (id INTEGER PRIMARY KEY, category TEXT NOT NULL, content TEXT NOT NULL, tags TEXT NOT NULL, created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP)"
+        )
+        connection.execute(
+            "CREATE TABLE IF NOT EXISTS preferences (key TEXT PRIMARY KEY, value TEXT NOT NULL, updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP)"
+        )
+
+    async def store_project_context(self, content: str, *, tags: tuple[str, ...] = ()) -> MemoryEntry:
+        return await self._store("project", content, tags)
+
+    async def remember_agent_information(self, content: str, *, tags: tuple[str, ...] = ()) -> MemoryEntry:
+        return await self._store("agent", content, tags)
+
+    async def remember_task(self, request: str, response: str) -> MemoryEntry:
+        tags = tuple(sorted(set(self._terms(request))))[:12]
+        return await self._store("task", f"Request: {request}\nResponse: {response[:4_000]}", tags)
+
+    async def record_workflow(
+        self,
+        request: str,
+        tool_sequence: tuple[str, ...] | list[str],
+        *,
+        success: bool,
+        error: str | None = None,
+        summary: str | None = None,
+    ) -> MemoryEntry:
+        payload = {
+            "request": request.strip(),
+            "tool_sequence": [str(tool) for tool in tool_sequence],
+            "success": bool(success),
+            "error": str(error or ""),
+            "summary": str(summary or ""),
+        }
+        terms = set(self._terms(request))
+        terms.update(self._terms(" ".join(payload["tool_sequence"])))
+        tags = tuple(sorted(terms))[:12]
+        return await self._store("workflow", json.dumps(payload, sort_keys=True), tags)
+
+    async def workflow_recommendations(self, query: str, *, limit: int = 4) -> list[dict[str, Any]]:
+        async with self._lock:
+            return await asyncio.to_thread(self._workflow_recommendations, query, limit)
+
+    async def set_preference(self, key: str, value: str) -> None:
+        if not key.strip() or not value.strip():
+            raise ValueError("Preference key and value are required.")
+        async with self._lock:
+            await asyncio.to_thread(self._set_preference, key.strip(), value.strip())
+
+    async def preferences(self) -> dict[str, str]:
+        async with self._lock:
+            return await asyncio.to_thread(self._preferences)
+
+    async def retrieve(self, query: str, *, limit: int = 6) -> list[MemoryEntry]:
+        async with self._lock:
+            return await asyncio.to_thread(self._retrieve, query, limit)
+
+    async def context_for(self, query: str, *, limit: int = 4) -> list[str]:
+        """Format durable preferences and relevant memories as approved context."""
+        preferences, entries = await asyncio.gather(self.preferences(), self.retrieve(query, limit=limit))
+        context = [f"User preference — {key}: {value}" for key, value in preferences.items()]
+        context.extend(f"Remembered {entry.category}: {entry.content}" for entry in entries)
+        return context
+
+    async def _store(self, category: str, content: str, tags: tuple[str, ...]) -> MemoryEntry:
+        clean_content = self._scrubber.redact(content).strip()
+        clean_tags = tuple(self._scrubber.redact(tag) for tag in tags)
+        if not clean_content:
+            raise ValueError("Memory content is required.")
+        async with self._lock:
+            return await asyncio.to_thread(
+                self._store_sync, category, clean_content, clean_tags
+            )
+
+    def _connection(self) -> sqlite3.Connection:
+        self.database_path.parent.mkdir(parents=True, exist_ok=True)
+        connection = sqlite3.connect(self.database_path)
+        connection.execute("PRAGMA journal_mode=WAL")
+        return connection
+
+    def _store_sync(self, category: str, content: str, tags: tuple[str, ...]) -> MemoryEntry:
+        with self._connection() as connection:
+            cursor = connection.execute(
+                "INSERT INTO memories(category, content, tags) VALUES (?, ?, ?)", (category, content, json.dumps(tags)),
+            )
+            row = connection.execute("SELECT id, category, content, tags, created_at FROM memories WHERE id = ?", (cursor.lastrowid,)).fetchone()
+        return self._entry(row)
+
+    def _set_preference(self, key: str, value: str) -> None:
+        key = self._scrubber.redact(key)
+        value = self._scrubber.redact(value)
+        with self._connection() as connection:
+            connection.execute(
+                "INSERT INTO preferences(key, value, updated_at) VALUES (?, ?, CURRENT_TIMESTAMP) ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = CURRENT_TIMESTAMP",
+                (key, value),
+            )
+
+    def _preferences(self) -> dict[str, str]:
+        with self._connection() as connection:
+            rows = connection.execute("SELECT key, value FROM preferences ORDER BY key").fetchall()
+        return {str(key): str(value) for key, value in rows}
+
+    def _retrieve(self, query: str, limit: int) -> list[MemoryEntry]:
+        terms = set(self._terms(query))
+        with self._connection() as connection:
+            rows = connection.execute("SELECT id, category, content, tags, created_at FROM memories ORDER BY id DESC").fetchall()
+        entries = [self._entry(row) for row in rows]
+        if not terms:
+            return entries[:limit]
+        ranked = [
+            (len(terms.intersection(self._terms(entry.content + " " + " ".join(entry.tags)))), entry)
+            for entry in entries
+        ]
+        return [entry for score, entry in sorted(ranked, key=lambda item: (-item[0], -item[1].id)) if score][:limit]
+
+    def _workflow_recommendations(self, query: str, limit: int) -> list[dict[str, Any]]:
+        terms = set(self._terms(query))
+        with self._connection() as connection:
+            rows = connection.execute(
+                "SELECT id, category, content, tags, created_at FROM memories WHERE category = 'workflow' ORDER BY id DESC"
+            ).fetchall()
+        workflow_entries = []
+        for row in rows:
+            entry = self._entry(row)
+            try:
+                payload = json.loads(entry.content)
+            except json.JSONDecodeError:
+                continue
+            if not isinstance(payload, dict):
+                continue
+            workflow_entries.append({
+                "id": entry.id,
+                "request": str(payload.get("request", "")),
+                "tool_sequence": list(payload.get("tool_sequence", [])),
+                "success": bool(payload.get("success")),
+                "error": str(payload.get("error", "")),
+                "summary": str(payload.get("summary", "")),
+                "created_at": entry.created_at,
+            })
+        if not terms:
+            return workflow_entries[:limit]
+        ranked = []
+        for workflow in workflow_entries:
+            score = len(terms.intersection(self._terms(workflow["request"] + " " + " ".join(workflow["tool_sequence"]))))
+            ranked.append((score, workflow))
+        sorted_workflows = [workflow for score, workflow in sorted(ranked, key=lambda item: (-item[0], -item[1]["id"])) if score]
+        return sorted_workflows[:limit]
+
+    @staticmethod
+    def _entry(row: tuple[Any, ...]) -> MemoryEntry:
+        return MemoryEntry(int(row[0]), str(row[1]), str(row[2]), tuple(json.loads(row[3])), str(row[4]))
+
+    @staticmethod
+    def _terms(value: str) -> list[str]:
+        return re.findall(r"[a-zA-Z_][a-zA-Z0-9_]*", value.lower())
+
+
+class MemoryContextSource:
+    """Adapter for the core Agent context protocol without importing it."""
+
+    def __init__(self, memory: LongTermMemory) -> None:
+        self.memory = memory
+
+    async def context_for(self, request: RequestWithMessage) -> list[str]:
+        return await self.memory.context_for(request.message)

pulse/mutations.py

@@ -0,0 +1,283 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import subprocess
+import uuid
+from collections.abc import Iterator
+from dataclasses import asdict, dataclass, field
+from datetime import UTC, datetime
+from difflib import unified_diff
+from pathlib import Path
+from typing import Self
+
+from pulse.subprocesses import isolated_process_kwargs, isolated_subprocess_environment
+from pulse.telemetry import get_correlation_id
+
+
+@dataclass(frozen=True)
+class FileSnapshot:
+    path: str
+    content: bytes
+    sha256: str
+
+
+@dataclass(frozen=True)
+class MutationEvent:
+    """An immutable, rollback-ready record of one workspace file mutation."""
+
+    schema_version: int = field(default=1, init=False)
+    transaction_id: str
+    correlation_id: str
+    timestamp: str
+    action: str
+    file_path: str
+    before_content: str | None
+    after_content: str | None
+    before_sha256: str | None
+    after_sha256: str | None
+    unified_diff: str
+    command: str | None
+    generated_by_command: bool
+    git_before: dict[str, object]
+    git_after: dict[str, object]
+
+
+class MutationTransaction:
+    def __init__(self, tracker: MutationTracker, *, command: str | None = None) -> None:
+        self.tracker = tracker
+        self.id = str(uuid.uuid4())
+        self.command = command
+        self._before = tracker._snapshot_workspace()
+        self._git_before = tracker.git_state()
+        self._closed = False
+
+    def finalize(self) -> list[MutationEvent]:
+        if self._closed:
+            return []
+        self._closed = True
+        after = self.tracker._snapshot_workspace()
+        git_after = self.tracker.git_state()
+        events = self.tracker._events_for_change(
+            self.id, self._before, after, self._git_before, git_after, self.command
+        )
+        self.tracker._append(events)
+        return events
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, exc_type, exc, traceback) -> bool:
+        self.finalize()
+        return False
+
+
+class MutationTracker:
+    """Capture file-system and Git changes made by Pulse operations.
+
+    Content snapshots are intentional: they provide the data required for a future
+    rollback implementation.  Consumers should protect `.agent/logs` because it may
+    contain the previous or replacement contents of edited files.
+    """
+
+    _IGNORED_PARTS = {  # noqa: RUF012
+        ".git",
+        ".agent",
+        ".agents",
+        ".pulse",
+        ".venv",
+        "venv",
+        "__pycache__",
+        ".pytest_cache",
+    }
+    _IGNORED_NAMES = {".env", "credentials.json"}  # noqa: RUF012
+    _IGNORED_SUFFIXES = {  # noqa: RUF012
+        ".crt", ".db", ".key", ".log", ".p12", ".pem", ".pfx", ".sqlite", ".sqlite3"
+    }
+
+    def __init__(self, workspace: Path, log_path: Path | None = None) -> None:
+        self.workspace = workspace.resolve()
+        self.log_path = log_path or self.workspace / ".agent" / "logs" / "mutations.jsonl"
+
+    def transaction(self, *, command: str | None = None) -> MutationTransaction:
+        return MutationTransaction(self, command=command)
+
+    def run_command(self, command: str, *, timeout: float | None = None) -> subprocess.CompletedProcess[str]:
+        """Run a workspace command and record every file it creates or changes."""
+        with self.transaction(command=command):
+            return subprocess.run(
+                command,
+                cwd=self.workspace,
+                shell=True,
+                text=True,
+                capture_output=True,
+                timeout=timeout,
+                check=False,
+                env=isolated_subprocess_environment(),
+                **isolated_process_kwargs(),
+            )
+
+    def git_state(self) -> dict[str, object]:
+        return {
+            "available": self._git("rev-parse", "--is-inside-work-tree") == "true",
+            "commit": self._git("rev-parse", "HEAD"),
+            "status": self._git("status", "--porcelain=v1"),
+            "changed_files": self._git_lines("status", "--porcelain=v1"),
+            "diff": self._git("diff", "--binary"),
+        }
+
+    def history(self) -> Iterator[dict[str, object]]:
+        if not self.log_path.exists():
+            return iter(())
+
+        def entries() -> Iterator[dict[str, object]]:
+            for line in self.log_path.read_text(encoding="utf-8").splitlines():
+                try:
+                    value = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if isinstance(value, dict):
+                    yield value
+
+        return entries()
+
+    def latest_transaction(self) -> list[dict[str, object]]:
+        events = list(self.history())
+        if not events:
+            return []
+        last_id = str(events[-1].get("transaction_id", ""))
+        return [event for event in events if event.get("transaction_id") == last_id]
+
+    def last_approved_edit(self) -> list[dict[str, object]]:
+        """Return the latest approved-edit transaction, excluding rollback logs."""
+        events = [event for event in self.history() if event.get("command") == "pulse approved edit"]
+        if not events:
+            return []
+        transaction_id = events[-1].get("transaction_id")
+        return [event for event in events if event.get("transaction_id") == transaction_id]
+
+    def _snapshot_workspace(self) -> dict[str, FileSnapshot]:
+        snapshots: dict[str, FileSnapshot] = {}
+        for path in self.workspace.rglob("*"):
+            relative = path.relative_to(self.workspace)
+            if (
+                any(part in self._IGNORED_PARTS for part in relative.parts)
+                or path.name.lower() in self._IGNORED_NAMES
+                or path.suffix.lower() in self._IGNORED_SUFFIXES
+                or path.is_symlink()
+                or not path.is_file()
+            ):
+                continue
+            content = path.read_bytes()
+            display_path = relative.as_posix()
+            snapshots[display_path] = FileSnapshot(display_path, content, self._hash(content))
+        return snapshots
+
+    def _events_for_change(
+        self,
+        transaction_id: str,
+        before: dict[str, FileSnapshot],
+        after: dict[str, FileSnapshot],
+        git_before: dict[str, object],
+        git_after: dict[str, object],
+        command: str | None,
+    ) -> list[MutationEvent]:
+        events: list[MutationEvent] = []
+        paths = sorted(set(before) | set(after))
+        for path in paths:
+            previous, current = before.get(path), after.get(path)
+            if previous and current and previous.sha256 == current.sha256:
+                continue
+            action = "create" if previous is None else "delete" if current is None else "modify"
+            events.append(self._event(transaction_id, action, path, previous, current, command, git_before, git_after))
+
+        # Detect a rename when a deleted file's exact content appears at a new path.
+        deleted = [event for event in events if event.action == "delete"]
+        created = [event for event in events if event.action == "create"]
+        replacements: dict[str, MutationEvent] = {}
+        removed: set[str] = set()
+        for old in deleted:
+            for new in created:
+                if old.before_sha256 == new.after_sha256:
+                    replacements[old.file_path] = MutationEvent(
+                        transaction_id=transaction_id,
+                        correlation_id=old.correlation_id,
+                        timestamp=old.timestamp,
+                        action="rename",
+                        file_path=f"{old.file_path} -> {new.file_path}",
+                        before_content=old.before_content,
+                        after_content=new.after_content,
+                        before_sha256=old.before_sha256,
+                        after_sha256=new.after_sha256,
+                        unified_diff="",
+                        command=command,
+                        generated_by_command=command is not None,
+                        git_before=git_before,
+                        git_after=git_after,
+                    )
+                    removed.add(new.file_path)
+                    break
+        return [event for event in events if event.file_path not in replacements and event.file_path not in removed] + list(replacements.values())
+
+    def _event(self, transaction_id: str, action: str, path: str, before: FileSnapshot | None, after: FileSnapshot | None, command: str | None, git_before: dict[str, object], git_after: dict[str, object]) -> MutationEvent:
+        before_text = self._decode(before.content) if before else None
+        after_text = self._decode(after.content) if after else None
+        return MutationEvent(
+            transaction_id=transaction_id,
+            correlation_id=get_correlation_id(),
+            timestamp=datetime.now(UTC).isoformat(),
+            action=action,
+            file_path=path,
+            before_content=before_text,
+            after_content=after_text,
+            before_sha256=before.sha256 if before else None,
+            after_sha256=after.sha256 if after else None,
+            unified_diff=self._diff(path, before_text, after_text),
+            command=command,
+            generated_by_command=command is not None,
+            git_before=git_before,
+            git_after=git_after,
+        )
+
+    def _append(self, events: list[MutationEvent]) -> None:
+        if not events:
+            return
+        self.log_path.parent.mkdir(parents=True, exist_ok=True)
+        with self.log_path.open("a", encoding="utf-8") as handle:
+            for event in events:
+                handle.write(json.dumps(asdict(event), separators=(",", ":")) + "\n")
+
+    def _git(self, *args: str) -> str | None:
+        result = subprocess.run(
+            ["git", *args],
+            cwd=self.workspace,
+            text=True,
+            capture_output=True,
+            check=False,
+            env=isolated_subprocess_environment(
+                {
+                    "GIT_CONFIG_NOSYSTEM": "1",
+                    "GIT_CONFIG_GLOBAL": str(Path(os.devnull)),
+                    "GIT_ATTR_NOSYSTEM": "1",
+                }
+            ),
+            **isolated_process_kwargs(),
+        )
+        return result.stdout.strip() if result.returncode == 0 else None
+
+    def _git_lines(self, *args: str) -> list[str]:
+        value = self._git(*args)
+        return value.splitlines() if value else []
+
+    @staticmethod
+    def _hash(content: bytes) -> str:
+        return hashlib.sha256(content).hexdigest()
+
+    @staticmethod
+    def _decode(content: bytes) -> str:
+        return content.decode("utf-8", errors="replace")
+
+    @staticmethod
+    def _diff(path: str, before: str | None, after: str | None) -> str:
+        return "".join(unified_diff((before or "").splitlines(keepends=True), (after or "").splitlines(keepends=True), fromfile=f"a/{path}", tofile=f"b/{path}"))

pulse/orchestration/__init__.py

@@ -0,0 +1,3 @@
+from pulse.orchestration.orchestrator import AgentOrchestrator
+
+__all__ = ["AgentOrchestrator"]

pulse/orchestration/orchestrator.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from pulse.context import ContextManager
+from pulse.core.agent import Agent, AgentRequest, AgentResponse
+from pulse.core.protocols import LLMProvider
+from pulse.repository import RepositoryIndex
+from pulse.safety.safety_manager import SafetyManager
+from pulse.tool_registry import ToolInvocation, ToolRegistry
+
+
+class AgentOrchestrator:
+    """Intercepts user prompts, queries Repository Intelligence, and manages tool/LLM execution flow.
+
+    - Intercepts user prompt.
+    - Runs Repository Intelligence.
+    - Executes tool directly if intent is deterministic (e.g. read file, search symbol, registered tool).
+    - Forwards to LLM only if intent is complex.
+    """
+
+    def __init__(
+        self,
+        agent: Agent | None = None,
+        provider: LLMProvider | None = None,
+        repository: RepositoryIndex | None = None,
+        tool_registry: ToolRegistry | None = None,
+        safety_manager: SafetyManager | None = None,
+        system_prompt: str = "You are a pulse project assistant.",
+        context_manager: ContextManager | None = None,
+    ) -> None:
+        self.repository = repository
+        self.tool_registry = tool_registry or ToolRegistry()
+        self.safety_manager = safety_manager or SafetyManager()
+        self.context_manager = context_manager
+
+        if agent:
+            self.agent = agent
+        elif provider:
+            self.agent = Agent(
+                provider=provider,
+                system_prompt=system_prompt,
+                tool_registry=self.tool_registry,
+            )
+        else:
+            self.agent = None
+
+    async def handle_request(self, request: AgentRequest | str) -> AgentResponse:
+        if isinstance(request, str):
+            request = AgentRequest(message=request)
+
+        prompt = request.message.strip()
+
+        # 1. Run Repository Intelligence
+        repo_results = []
+        if self.repository:
+            repo_results = await self.repository.search(prompt)
+
+        # 2. Execute tool directly if intent is deterministic
+        deterministic_response = await self._try_deterministic_execution(prompt, repo_results, request)
+        if deterministic_response is not None:
+            return deterministic_response
+
+        # 3. Forward to LLM only if intent is complex
+        if not self.agent:
+            return AgentResponse(
+                content="No LLM agent or provider configured for handling complex prompts.",
+                conversation_id=request.conversation_id,
+                request_id=str(request.metadata.get("request_id", "local")),
+            )
+
+        context = list(request.context)
+
+        # Prepend ContextManager output (ranked, compressed, token-budgeted)
+        # before raw repository results so the LLM sees the most relevant
+        # context first.
+        if self.context_manager:
+            managed_context = await self.context_manager.as_strings(prompt)
+            context = [*managed_context, *context]
+
+        if repo_results:
+            repo_context = "Repository Intelligence Context:\n" + "\n".join(
+                f"- {item.path} (score: {item.score})" for item in repo_results
+            )
+            context.append(repo_context)
+
+        enriched_request = AgentRequest(
+            message=request.message,
+            conversation_id=request.conversation_id,
+            context=context,
+            metadata=request.metadata,
+        )
+
+        return await self.agent.respond(enriched_request)
+
+    async def _try_deterministic_execution(
+        self, prompt: str, repo_results: list[Any], request: AgentRequest
+    ) -> AgentResponse | None:
+        prompt_lower = prompt.lower()
+        request_id = str(request.metadata.get("request_id", "deterministic"))
+
+        # Check explicit tool registry match
+        invocation = ToolInvocation(message=prompt, metadata=request.metadata)
+        matched_tool = self.tool_registry.match(invocation)
+        if matched_tool:
+            authorized = await self.safety_manager.authorize(
+                action=matched_tool.name,
+                target=prompt,
+                detail=f"Deterministic tool execution: {matched_tool.name}",
+            )
+            if not authorized:
+                return AgentResponse(
+                    content=f"Execution blocked by SafetyManager for tool: {matched_tool.name}",
+                    conversation_id=request.conversation_id,
+                    request_id=request_id,
+                    tool_name=matched_tool.name,
+                )
+
+            tool_result = await self.tool_registry.execute(invocation)
+            content = tool_result.content if tool_result else "Tool executed."
+            return AgentResponse(
+                content=content,
+                conversation_id=request.conversation_id,
+                request_id=request_id,
+                tool_name=matched_tool.name,
+            )
+
+        # Deterministic symbol search intent
+        if self.repository and any(kw in prompt_lower for kw in ["search symbol", "find symbol", "lookup symbol"]):
+            symbol_query = re.sub(r"(?i)^(search|find|lookup)\s+symbol\s*", "", prompt).strip()
+            if symbol_query:
+                matches = await self.repository.search(symbol_query)
+                found_symbols = []
+                for m in matches:
+                    for s in m.symbols:
+                        if symbol_query.lower() in s.name.lower():
+                            found_symbols.append(f"- `{s.name}` ({s.kind}) in `{m.path}` at line {s.line}")
+                content = (
+                    "Symbol search results:\n" + "\n".join(found_symbols)
+                    if found_symbols
+                    else f"No symbols matching '{symbol_query}' found."
+                )
+                return AgentResponse(
+                    content=content,
+                    conversation_id=request.conversation_id,
+                    request_id=request_id,
+                    tool_name="repository_symbol_search",
+                )
+
+        # Deterministic file read / listing intent
+        if self.repository and ("list files" in prompt_lower or "show files" in prompt_lower):
+            files = await self.repository.files()
+            content = "Repository files:\n" + "\n".join(f"- {f}" for f in files)
+            return AgentResponse(
+                content=content,
+                conversation_id=request.conversation_id,
+                request_id=request_id,
+                tool_name="repository_list_files",
+            )
+
+        return None