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

pulse/repository.py

@@ -0,0 +1,209 @@
+"""Async incremental repository indexing and lexical semantic retrieval."""
+
+from __future__ import annotations
+
+import ast
+import asyncio
+import hashlib
+import json
+import re
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class Symbol:
+    name: str
+    kind: str
+    line: int
+
+
+@dataclass(slots=True)
+class IndexedFile:
+    path: str
+    fingerprint: str
+    imports: list[str] = field(default_factory=list)
+    symbols: list[Symbol] = field(default_factory=list)
+    terms: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True, slots=True)
+class IndexReport:
+    files: int
+    folders: int
+    indexed: int
+    unchanged: int
+    removed: int
+
+
+@dataclass(frozen=True, slots=True)
+class SearchResult:
+    path: str
+    score: float
+    symbols: tuple[Symbol, ...]
+
+
+class RepositoryIndex:
+    """Persists metadata under `.agent` and reparses only changed files."""
+
+    _IGNORED = {".git", ".agent", ".agents", ".venv", "venv", "__pycache__", ".pytest_cache", "node_modules"}  # noqa: RUF012
+    _IGNORED_NAMES = {".env", "credentials.json"}  # noqa: RUF012
+    _IGNORED_SUFFIXES = {  # noqa: RUF012
+        ".crt", ".db", ".key", ".log", ".p12", ".pem", ".pfx", ".sqlite", ".sqlite3"
+    }
+    _MAX_INDEX_FILE_BYTES = 2_097_152
+    _MAX_SAVED_INDEX_BYTES = 16_777_216
+
+    def __init__(self, workspace: Path, index_path: Path | None = None) -> None:
+        self.workspace = workspace.resolve()
+        self.index_path = index_path or self.workspace / ".agent" / "repository-index.json"
+        self._files: dict[str, IndexedFile] = {}
+        self._folders: set[str] = set()
+        self._loaded = False
+        self._lock = asyncio.Lock()
+
+    async def index(self) -> IndexReport:
+        async with self._lock:
+            return await asyncio.to_thread(self._index_sync)
+
+    async def search(self, query: str, *, limit: int = 6) -> list[SearchResult]:
+        """Return filename and lexical-semantic matches without exposing storage."""
+        await self.index()
+        query_terms = set(self._terms(query))
+        query_lower = query.lower()
+        results: list[SearchResult] = []
+        for item in self._files.values():
+            path_lower = item.path.lower()
+            score = float(4 if query_lower and query_lower in path_lower else 0)
+            score += 2 * len(query_terms.intersection(self._terms(Path(item.path).name)))
+            score += len(query_terms.intersection(item.terms))
+            score += 2 * len(query_terms.intersection({symbol.name.lower() for symbol in item.symbols}))
+            if score:
+                results.append(SearchResult(item.path, score, tuple(item.symbols)))
+        return sorted(results, key=lambda result: (-result.score, result.path))[:limit]
+
+    async def symbols(self, file_path: str) -> list[Symbol]:
+        await self.index()
+        return list(self._files.get(self._normalise_path(file_path), IndexedFile("", "")).symbols)
+
+    async def details(self, file_path: str) -> IndexedFile | None:
+        await self.index()
+        return self._files.get(self._normalise_path(file_path))
+
+    async def files(self) -> list[str]:
+        await self.index()
+        return sorted(self._files)
+
+    def _index_sync(self) -> IndexReport:
+        self._load()
+        current: dict[str, Path] = {}
+        folders: set[str] = set()
+        for path in self.workspace.rglob("*"):
+            relative = path.relative_to(self.workspace)
+            if any(part in self._IGNORED for part in relative.parts):
+                continue
+            if path.name.lower() in self._IGNORED_NAMES or path.suffix.lower() in self._IGNORED_SUFFIXES:
+                continue
+            if path.is_symlink():
+                continue
+            if path.is_dir():
+                folders.add(relative.as_posix())
+            elif path.is_file():
+                current[relative.as_posix()] = path
+
+        indexed = unchanged = 0
+        for relative, path in current.items():
+            fingerprint = self._fingerprint(path)
+            existing = self._files.get(relative)
+            if existing and existing.fingerprint == fingerprint:
+                unchanged += 1
+                continue
+            self._files[relative] = self._parse(relative, path, fingerprint)
+            indexed += 1
+        removed_paths = set(self._files) - set(current)
+        for relative in removed_paths:
+            del self._files[relative]
+        folders_changed = folders != self._folders
+        self._folders = folders
+        # Avoid rewriting the index on a no-op refresh.  This matters because
+        # search refreshes the index before serving a result.
+        if indexed or removed_paths or folders_changed or not self.index_path.exists():
+            self._save()
+        return IndexReport(len(self._files), len(folders), indexed, unchanged, len(removed_paths))
+
+    def _load(self) -> None:
+        if self._loaded:
+            return
+        self._loaded = True
+        if not self.index_path.exists():
+            return
+        if self.index_path.is_symlink() or self.index_path.stat().st_size > self._MAX_SAVED_INDEX_BYTES:
+            self._files, self._folders = {}, set()
+            return
+        try:
+            raw = json.loads(self.index_path.read_text(encoding="utf-8"))
+            self._folders = set(raw.get("folders", []))
+            for value in raw.get("files", []):
+                value["symbols"] = [Symbol(**symbol) for symbol in value.get("symbols", [])]
+                item = IndexedFile(**value)
+                self._files[item.path] = item
+        except (json.JSONDecodeError, TypeError, KeyError):
+            self._files, self._folders = {}, set()
+
+    def _save(self) -> None:
+        self.index_path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "version": 1,
+            "folders": sorted(self._folders),
+            "files": [asdict(item) for item in sorted(self._files.values(), key=lambda item: item.path)],
+        }
+        temporary_path = self.index_path.with_suffix(".tmp")
+        temporary_path.write_text(json.dumps(payload, separators=(",", ":")), encoding="utf-8")
+        temporary_path.replace(self.index_path)
+
+    def _parse(self, relative: str, path: Path, fingerprint: str) -> IndexedFile:
+        if path.is_symlink() or path.stat().st_size > self._MAX_INDEX_FILE_BYTES:
+            return IndexedFile(relative, fingerprint, terms=sorted(set(self._terms(relative))))
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            text = ""
+        imports: list[str] = []
+        symbols: list[Symbol] = []
+        if path.suffix == ".py":
+            try:
+                tree = ast.parse(text)
+                for node in ast.walk(tree):
+                    if isinstance(node, ast.Import):
+                        imports.extend(alias.name for alias in node.names)
+                    elif isinstance(node, ast.ImportFrom):
+                        imports.extend(f"{node.module or ''}.{alias.name}".strip(".") for alias in node.names)
+                    elif isinstance(node, ast.ClassDef):
+                        symbols.append(Symbol(node.name, "class", node.lineno))
+                    elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                        symbols.append(Symbol(node.name, "function", node.lineno))
+            except SyntaxError:
+                pass
+        terms = sorted(set(self._terms(relative) + self._terms(text[:50_000]) + [symbol.name.lower() for symbol in symbols]))
+        return IndexedFile(relative, fingerprint, imports, symbols, terms)
+
+    @staticmethod
+    def _fingerprint(path: Path) -> str:
+        stat = path.stat()
+        return hashlib.sha256(f"{stat.st_mtime_ns}:{stat.st_size}".encode()).hexdigest()
+
+    @staticmethod
+    def _terms(text: str) -> list[str]:
+        words = re.findall(r"[a-zA-Z_][a-zA-Z0-9_]*", text.lower())
+        # Preserve identifiers while also matching their snake_case components.
+        return words + [part for word in words for part in word.split("_") if part]
+
+    def _normalise_path(self, file_path: str) -> str:
+        """Convert a CLI path to the portable path stored in the index."""
+        candidate = Path(file_path)
+        if candidate.is_absolute():
+            try:
+                candidate = candidate.resolve().relative_to(self.workspace)
+            except ValueError:
+                return ""
+        return candidate.as_posix()

pulse/rpc.py

@@ -0,0 +1,249 @@
+"""JSON-RPC 2.0 adapter for Pulse, with an optional local WebSocket server."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import hmac
+import json
+import os
+from pathlib import Path
+from typing import Any, Protocol
+
+from pulse import __version__
+from pulse.config import load_agent_config
+from pulse.runtime import build_runtime
+from pulse.telemetry import get_correlation_id, set_correlation_id
+from pulse.tool_registry import ToolInvocation
+
+RPC_PROTOCOL_VERSION = "1.0"
+RPC_COMPATIBLE_MAJOR = 1
+RPC_MAX_PROMPT_CHARS = 100_000
+RPC_MAX_CONTEXT_ITEMS = 64
+RPC_MAX_CONTEXT_CHARS = 500_000
+RPC_COMMAND_ALLOWLIST = frozenset({"doctor", "git", "index", "search", "status", "symbols"})
+RPC_METHODS = (
+    "pulse.ask",
+    "pulse.askStream",
+    "pulse.codeAction",
+    "pulse.command",
+    "pulse.health",
+    "pulse.protocolVersion",
+    "pulse.stream",
+)
+
+
+class PulseRpcEngine(Protocol):
+    async def respond_remote(self, prompt: str, context: list[str]) -> str: ...
+
+
+class JsonRpcDispatcher:
+    """Transport-neutral JSON-RPC dispatcher; easy to test without sockets."""
+
+    def __init__(self, runtime: Any) -> None:
+        self.runtime = runtime
+
+    async def dispatch(self, message: dict[str, Any]) -> dict[str, Any] | None:
+        request_id = message.get("id")
+        if message.get("jsonrpc") != "2.0" or not isinstance(message.get("method"), str):
+            return self._error(request_id, -32600, "Invalid JSON-RPC request.")
+        method, params = message["method"], message.get("params", {})
+        if not isinstance(params, dict):
+            return self._error(request_id, -32602, "Parameters must be an object.")
+        requested_protocol = params.get("protocol_version")
+        if requested_protocol is not None and not self._is_compatible_protocol(
+            requested_protocol
+        ):
+            return self._error(
+                request_id,
+                -32001,
+                "Unsupported Pulse RPC protocol version.",
+            )
+        correlation_id = set_correlation_id(params.get("correlation_id"))
+        try:
+            if method == "pulse.health":
+                result: Any = {
+                    "status": "ok",
+                    "service_version": __version__,
+                    "protocol_version": RPC_PROTOCOL_VERSION,
+                }
+            elif method == "pulse.protocolVersion":
+                result = {
+                    "protocol_version": RPC_PROTOCOL_VERSION,
+                    "compatible_major": RPC_COMPATIBLE_MAJOR,
+                    "methods": list(RPC_METHODS),
+                }
+            elif method in {"pulse.ask", "pulse.codeAction"}:
+                prompt = str(params.get("prompt", "")).strip()
+                if not prompt:
+                    return self._error(request_id, -32602, "A prompt is required.")
+                if len(prompt) > RPC_MAX_PROMPT_CHARS:
+                    return self._error(request_id, -32602, "The prompt exceeds the size limit.")
+                raw_context = params.get("context", [])
+                if not isinstance(raw_context, list) or any(
+                    not isinstance(item, str) for item in raw_context
+                ):
+                    return self._error(request_id, -32602, "Context must be an array of strings.")
+                if len(raw_context) > RPC_MAX_CONTEXT_ITEMS or sum(
+                    len(item) for item in raw_context
+                ) > RPC_MAX_CONTEXT_CHARS:
+                    return self._error(request_id, -32602, "Context exceeds the size limit.")
+                context = list(raw_context)
+                result = {"content": await self.runtime.agent.respond_remote(prompt, context)}
+            elif method in {"pulse.askStream", "pulse.stream"}:
+                prompt = str(params.get("prompt", "")).strip()
+                if not prompt:
+                    return self._error(request_id, -32602, "A prompt is required.")
+                if len(prompt) > RPC_MAX_PROMPT_CHARS:
+                    return self._error(request_id, -32602, "The prompt exceeds the size limit.")
+                from pulse.streaming import StreamingExecutionEngine
+                engine = StreamingExecutionEngine(
+                    provider=getattr(self.runtime, "provider", None),
+                    task_manager=getattr(self.runtime, "task_manager", None),
+                    tool_registry=getattr(self.runtime, "tools", None),
+                )
+                events = []
+                async for event in engine.execute_stream(prompt):
+                    events.append(event.to_dict())
+                result = {"events": events, "completed": True}
+            elif method == "pulse.command":
+                name = str(params.get("name", ""))
+                if name not in RPC_COMMAND_ALLOWLIST:
+                    return self._error(
+                        request_id,
+                        -32602,
+                        "This command is unavailable through RPC because interactive approval is required.",
+                    )
+                arguments = params.get("arguments", {})
+                if not isinstance(arguments, dict):
+                    return self._error(request_id, -32602, "Command arguments must be an object.")
+                tool_result = await self.runtime.tools.execute(
+                    ToolInvocation(name=name, arguments=arguments)
+                )
+                if tool_result is None:
+                    return self._error(request_id, -32601, "Unknown Pulse command.")
+                result = {"content": tool_result.content, "metadata": self._json_metadata(tool_result.metadata)}
+            else:
+                return self._error(request_id, -32601, f"Method not found: {method}")
+        except Exception:  # Boundary adapter: return protocol errors, never tracebacks.  # noqa: BLE001
+            return self._error(request_id, -32000, "Internal Pulse error.")
+        return None if request_id is None else {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "result": result,
+            "correlation_id": correlation_id,
+            "pulse_protocol_version": RPC_PROTOCOL_VERSION,
+        }
+
+    @staticmethod
+    def _is_compatible_protocol(value: object) -> bool:
+        if not isinstance(value, str):
+            return False
+        major, separator, minor = value.partition(".")
+        return separator == "." and major.isdigit() and minor.isdigit() and int(major) == RPC_COMPATIBLE_MAJOR
+
+    @staticmethod
+    def _error(request_id: object, code: int, message: str) -> dict[str, Any]:
+        return {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "error": {"code": code, "message": message},
+            "correlation_id": get_correlation_id(),
+            "pulse_protocol_version": RPC_PROTOCOL_VERSION,
+        }
+
+    @staticmethod
+    def _json_metadata(metadata: dict[str, Any]) -> dict[str, str]:
+        allowed = {"correlation_id", "error_code", "permission_denied"}
+        return {key: str(value) for key, value in metadata.items() if key in allowed}
+
+
+def _valid_rpc_token(token: str | None) -> bool:
+    if token is None or len(token) < 32 or len(token) > 512:
+        return False
+    lowered = token.lower()
+    return lowered not in {"changeme", "replace_me", "placeholder"} and len(set(token)) >= 8
+
+
+def _authorized_rpc_header(header: str | None, token: str) -> bool:
+    if not header or not header.startswith("Bearer "):
+        return False
+    candidate = header.removeprefix("Bearer ")
+    return bool(candidate) and hmac.compare_digest(candidate, token)
+
+
+async def serve(
+    workspace: str,
+    host: str = "127.0.0.1",
+    port: int = 8765,
+    *,
+    auth_token: str | None = None,
+) -> None:
+    """Serve Pulse over loopback WebSocket transport using JSON-RPC messages."""
+    if host.strip().lower() not in {"127.0.0.1", "::1", "localhost"}:
+        raise ValueError("pulse-rpc is a local-only service and must bind to loopback.")
+    token = auth_token or os.environ.get("PULSE_RPC_TOKEN")
+    if not _valid_rpc_token(token):
+        raise ValueError(
+            "PULSE_RPC_TOKEN must be a non-placeholder secret of 32-512 characters."
+        )
+    assert token is not None
+    try:
+        from websockets.asyncio.server import serve as websocket_serve
+    except ImportError as error:
+        raise RuntimeError("WebSocket support requires the 'websockets' package. Run `uv sync`.") from error
+
+    workspace_path = Path(workspace).resolve()
+    runtime = build_runtime(workspace_path, load_agent_config(workspace_path))
+    dispatcher = JsonRpcDispatcher(runtime)
+
+    async def handler(websocket: Any) -> None:
+        async for raw in websocket:
+            try:
+                payload = json.loads(raw)
+                if not isinstance(payload, dict):
+                    response = JsonRpcDispatcher._error(None, -32600, "Invalid JSON-RPC request.")
+                else:
+                    response = await dispatcher.dispatch(payload)
+            except (json.JSONDecodeError, RecursionError, TypeError, ValueError):
+                response = JsonRpcDispatcher._error(None, -32700, "Parse error.")
+            if response is not None:
+                await websocket.send(json.dumps(response))
+
+    async def authenticate(_connection: Any, request: Any) -> Any | None:
+        if _authorized_rpc_header(request.headers.get("Authorization"), token):
+            return None
+        from websockets.datastructures import Headers
+        from websockets.http11 import Response
+
+        return Response(401, "Unauthorized", Headers(), b"Unauthorized")
+
+    async with websocket_serve(
+        handler,
+        host,
+        port,
+        max_size=1_048_576,
+        process_request=authenticate,
+    ):
+        print(f"Pulse JSON-RPC server listening on ws://{host}:{port}")
+        await asyncio.get_running_loop().create_future()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="pulse-rpc", description="Run Pulse's local JSON-RPC WebSocket server.")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument("--workspace", default=".")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8765)
+    args = parser.parse_args()
+    try:
+        asyncio.run(serve(args.workspace, args.host, args.port))
+    except KeyboardInterrupt:
+        raise SystemExit(130) from None
+    except (OSError, RuntimeError, ValueError):
+        print("pulse-rpc failed to start. Check host, port, workspace, and token settings.")
+        raise SystemExit(1) from None
+
+
+if __name__ == "__main__":
+    main()

pulse/rule_synthesizer.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from collections import Counter
+from pathlib import Path
+
+from pulse.episodic import EpisodicMemory
+
+
+class RuleSynthesizer:
+    """Extracts repeated error resolution patterns from episodic memory and auto-generates guidelines into `.agent/rules`."""
+
+    def __init__(
+        self,
+        memory: EpisodicMemory,
+        rules_dir: Path | None = None,
+        frequency_threshold: int = 2,
+    ) -> None:
+        self.memory = memory
+        self.rules_dir = rules_dir or Path(".agent/rules")
+        self.frequency_threshold = frequency_threshold
+
+    def synthesize_rules(self) -> list[Path]:
+        traces = self.memory.get_all_traces()
+        if not traces:
+            return []
+
+        pattern_counter: Counter[str] = Counter()
+        resolutions_by_error: dict[str, str] = {}
+
+        for trace in traces:
+            if not trace.error.strip() or not trace.resolution.strip():
+                continue
+            error_key = trace.error.strip().splitlines()[0][:60]
+            pattern_counter[error_key] += 1
+            resolutions_by_error[error_key] = trace.resolution.strip()
+
+        self.rules_dir.mkdir(parents=True, exist_ok=True)
+        generated_rules: list[Path] = []
+
+        rule_idx = 1
+        for error_key, count in pattern_counter.items():
+            if count >= self.frequency_threshold:
+                rule_file = self.rules_dir / f"rule_{rule_idx:03d}.md"
+                content = (
+                    f"# Auto-Synthesized Rule {rule_idx:03d}\n\n"
+                    f"**Trigger Error Pattern:**\n```\n{error_key}\n```\n\n"
+                    f"**Frequency Observed:** {count} times\n\n"
+                    f"**Recommended Resolution Guideline:**\n{resolutions_by_error[error_key]}\n"
+                )
+                rule_file.write_text(content, encoding="utf-8")
+                generated_rules.append(rule_file)
+                rule_idx += 1
+
+        return generated_rules