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

pulse/__init__.py

@@ -0,0 +1,5 @@
+"""Pulse package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

pulse/__main__.py

@@ -0,0 +1,4 @@
+from pulse.cli import main
+
+if __name__ == "__main__":
+    main()

pulse/agent.py

@@ -0,0 +1,270 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+
+from pulse.agent_manager import AgentManager
+from pulse.audit import AuditLog
+from pulse.cli_ui import print_answer, print_error, print_info, print_warning
+from pulse.context import ContextManager
+from pulse.core.agent import Agent, AgentRequest
+from pulse.memory import LongTermMemory, MemoryContextSource
+from pulse.provider import ChatMessage, ModelProvider
+from pulse.repository import RepositoryIndex
+from pulse.sandbox import ProjectSandbox
+from pulse.tool_registry import ToolRegistry
+
+
+@dataclass(frozen=True)
+class FileContext:
+    file: str
+    content: str
+
+
+class ProjectAgent:
+    def __init__(
+        self,
+        name: str,
+        sandbox: ProjectSandbox,
+        provider: ModelProvider,
+        audit: AuditLog,
+        tools: ToolRegistry | None = None,
+        repository: RepositoryIndex | None = None,
+        memory: LongTermMemory | None = None,
+        manager: AgentManager | None = None,
+        context_manager: ContextManager | None = None,
+    ) -> None:
+        self.name = name
+        self.sandbox = sandbox
+        self.provider = provider
+        self.audit = audit
+        self.repository = repository
+        self.memory = memory
+        self.manager = manager
+        self.tools = tools
+        self.context_manager = context_manager
+        self._orchestrator = Agent(
+            provider,
+            system_prompt=(
+                f"You are {name}, a single-model, read-only project assistant. "
+                "For normal conversation, answer directly without using project files. "
+                "For project work, use only approved project context. If more context is needed, say which file should be approved next.\n\n"
+                "When answering architecture, design, or overview questions, you must write a comprehensive and deeply detailed explanation based on the retrieved context files.\n"
+                "You must organize your answer using exactly these 6 headings:\n"
+                "1. Project overview\n2. Main components\n3. Data flow\n4. Agent workflow\n"
+                "5. Key technologies\n6. Execution flow\n\n"
+                "CRITICAL: Do not just output the headings. You MUST write at least one full paragraph of descriptive text under each heading, analyzing the project files. "
+                "Do not repeat these instructions, and do not return raw file contents."
+            ), context_source=MemoryContextSource(memory) if memory else None, tool_registry=tools,
+        )
+
+    def ask(self, question: str, *, auto_approve_reads: bool = False) -> None:
+        if not question:
+            print_warning("Please pass a question.")
+            return
+
+        self.audit.record("question", ".", "Question received.")
+        use_project_context = self._needs_project_context(question)
+        project_files = self.sandbox.list_files() if use_project_context else []
+        relevant_files: list[str] = []
+        if use_project_context and self.repository:
+            relevant = asyncio.run(self.repository.search(question))
+            relevant_files = [result.path for result in relevant]
+            project_files = relevant_files + [file for file in project_files if file not in relevant_files]
+        context = (
+            []
+            if not use_project_context or self._is_file_listing_question(question)
+            else self._collect_context(question, project_files, relevant_files, auto_approve_reads=auto_approve_reads)
+        )
+
+        if not self.provider.is_configured:
+            self._print_local_answer(question, project_files, context)
+            api_key_env_var = getattr(self.provider, "api_key_env_var", "the provider API key")
+            print_warning(
+                f"\nModel call skipped: run `pulse keys` to configure {api_key_env_var} securely."
+            )
+            return
+
+        self.audit.record("model-call", ".", f"Using {self.provider.config.provider}:{self.provider.config.name}.")
+        try:
+            approved_context = [f"File: {item.file}\n---\n{item.content}" for item in context]
+            if project_files and not approved_context:
+                approved_context.append("Project files:\n" + "\n".join(f"- {file}" for file in project_files))
+
+            # Prepend ranked, token-budgeted context from the ContextManager
+            # so the model receives the most relevant signals first.
+            if self.context_manager:
+                managed = asyncio.run(self.context_manager.as_strings(question))
+                approved_context = [*managed, *approved_context]
+
+            matched_tool = tools_match(self.tools, question)
+            if self.manager and not matched_tool and not self._is_architecture_question(question):
+                response_content = asyncio.run(self.manager.run(question, approved_context)).final_response
+            else:
+                response_content = asyncio.run(self._orchestrator.respond(AgentRequest(message=question, context=approved_context))).content
+            print_answer(response_content)
+            if self.memory:
+                asyncio.run(self.memory.remember_task(question, response_content))
+        except RuntimeError as error:
+            print_error(f"\nModel call failed: {error}")
+            print_error(self._provider_recovery_hint(error))
+
+    async def respond_remote(self, prompt: str, context: list[str]) -> str:
+        """Serve an IDE/client prompt without importing any transport concerns."""
+        self.audit.record("remote-question", ".", "Remote question received.")
+
+        # Prepend managed context (ranked, token-budgeted) from ContextManager
+        # before caller-supplied context so the model sees the best signals first.
+        if self.context_manager:
+            managed = await self.context_manager.as_strings(prompt)
+            context = [*managed, *context]
+
+        matched_tool = tools_match(self.tools, prompt)
+        if self.manager and not matched_tool and not self._is_architecture_question(prompt):
+            memory_context = await self.memory.context_for(prompt) if self.memory else []
+            response = (await self.manager.run(prompt, (*context, *memory_context))).final_response
+        else:
+            response = (await self._orchestrator.respond(AgentRequest(message=prompt, context=context))).content
+        if self.memory:
+            await self.memory.remember_task(prompt, response)
+        return response
+
+    def _collect_context(self, question: str, project_files: list[str], relevant_files: list[str] | None = None, *, auto_approve_reads: bool) -> list[FileContext]:
+        selected = self._select_context_files(question, project_files, relevant_files or [])
+        context: list[FileContext] = []
+
+        for file in selected:
+            content = self.sandbox.read_file(
+                file,
+                f"{self.name} wants to inspect this file for your question.",
+                auto_approve=auto_approve_reads,
+            )
+            if content is not None:
+                context.append(FileContext(file=file, content=content))
+
+        return context
+
+    def _is_architecture_question(self, question: str) -> bool:
+        lower = question.lower()
+        return any(term in lower for term in ("architecture", "design", "overview", "structure"))
+
+    def _select_context_files(self, question: str, project_files: list[str], relevant_files: list[str] | None = None) -> list[str]:
+        lower = question.lower()
+        explicit = [file for file in project_files if file.lower() in lower]
+        if explicit:
+            return explicit[:6]
+            
+        if self._is_architecture_question(question):
+            arch_files = {
+                "README.md",
+                "src/pulse/runtime.py",
+                "src/pulse/agent.py",
+                "src/pulse/agent_manager.py",
+                "src/pulse/context.py",
+                "src/pulse/reasoning.py",
+            }
+            results = [file for file in project_files if file.replace("\\", "/") in arch_files]
+            if relevant_files:
+                results.extend(file for file in relevant_files if file not in results)
+            return results[:6]
+
+        # The repository index is consulted before this point.  Prefer its
+        # ranked candidates to a static starter set so project questions reach
+        # the model with the files most likely to answer them.
+        if relevant_files:
+            return relevant_files[:6]
+
+        useful = {
+            "README.md",
+            "pyproject.toml",
+            "agent.config.json",
+            ".gitignore",
+            "src/pulse/cli.py",
+        }
+        return [file for file in project_files if file.replace("\\", "/") in useful][:6]
+
+    def _needs_project_context(self, question: str) -> bool:
+        lower = question.lower()
+        project_terms = {
+            "agent.config",
+            "bug",
+            "build",
+            "change",
+            "cli",
+            "code",
+            "debug",
+            "error",
+            "file",
+            "fix",
+            "implement",
+            "project",
+            "pyproject",
+            "readme",
+            "repo",
+            "repository",
+            "src/",
+            "test",
+            "traceback",
+            "update",
+        }
+        return any(term in lower for term in project_terms) or self._is_architecture_question(question)
+
+    def _is_file_listing_question(self, question: str) -> bool:
+        lower = question.lower()
+        return "file" in lower and any(term in lower for term in ("list", "show", "what files", "which files"))
+
+    def _build_messages(self, question: str, context: list[FileContext], project_files: list[str] | None = None) -> list[ChatMessage]:
+        file_blocks = "\n\n".join(f"File: {item.file}\n---\n{item.content}" for item in context)
+        project_file_block = "\n".join(f"- {file}" for file in (project_files or []))
+        context_block = file_blocks
+        if project_file_block and not file_blocks:
+            context_block = f"Project files:\n{project_file_block}"
+
+        system = (
+            f"You are {self.name}, a single-model, read-only project assistant. "
+            "For normal conversation, answer directly without using project files. "
+            "For project work, use only approved project context. If more context is needed, say which file should be approved next."
+        )
+        user = f"Question: {question}\n\n{context_block or 'No project context was requested or approved.'}"
+        return [ChatMessage(role="system", content=system), ChatMessage(role="user", content=user)]
+
+    def _print_local_answer(self, question: str, files: list[str], context: list[FileContext]) -> None:
+        print_info(f"\n{self.name} local answer:")
+        if "file" in question.lower():
+            print_info("\n".join(f"- {file}" for file in files) if files else "No project files found.")
+            return
+
+        if not context:
+            print_warning("No model is configured yet, so I can only answer project file-listing questions locally.")
+            return
+
+        read_files = ", ".join(item.file for item in context)
+        api_key_env_var = getattr(self.provider, "api_key_env_var", "the provider API key")
+        print_info(
+            f"I read {read_files}. Run `pulse keys` to configure {api_key_env_var} securely."
+        )
+
+    def _provider_recovery_hint(self, error: RuntimeError) -> str:
+        provider_name = self.provider.config.provider
+        if provider_name == "openrouter":
+            if "(402)" in str(error):
+                return (
+                    "OpenRouter accepted the API key but cannot charge this request. "
+                    "Add credits or use a model your OpenRouter account can access, then retry."
+                )
+            if "(401)" in str(error) or "(403)" in str(error):
+                return "OpenRouter rejected the API key or model access. Check OPENROUTER_API_KEY and the selected model."
+            return (
+                "OpenRouter returned an error. Check your OpenRouter credits/billing and API key, "
+                "or switch providers with `pulse model`."
+            )
+        return f"Check the {provider_name} API key, model name, and account status, then try again."
+
+
+def tools_match(tools: ToolRegistry | None, message: str) -> bool:
+    """Keep explicit/local tool requests on the established tool execution path."""
+    if tools is None:
+        return False
+    from pulse.tool_registry import ToolInvocation
+
+    return tools.match(ToolInvocation(message=message)) is not None

pulse/agent_manager.py

@@ -0,0 +1,335 @@
+"""Production-grade Multi-Agent Collaboration System for Pulse.
+
+Provides dynamic task assignment, parallel execution, conflict resolution,
+and shared context messaging between specialized agents.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncGenerator
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from pulse.context import ContextManager
+from pulse.core.agent import Agent, AgentRequest
+from pulse.core.protocols import LLMProvider
+from pulse.streaming import CancellationToken, StreamEvent, StreamEventType
+from pulse.task_manager import Task, TaskManager, TaskStatus
+from pulse.tool_registry import ToolRegistry
+
+
+class TaskCategory(Enum):
+    """Categories of tasks for dynamic assignment to specialized agents."""
+    PLANNING = "planning"
+    CODING = "coding"
+    REVIEW = "review"
+    TESTING = "testing"
+    DOCUMENTATION = "documentation"
+    GIT = "git"
+    GENERAL = "general"
+
+
+@dataclass(slots=True)
+class AgentMessage:
+    """A structured message passed between agents via the shared context."""
+    sender: str
+    recipient: str | None
+    category: TaskCategory
+    content: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class CollaborationContext:
+    """A blackboard for shared context and messages between agents."""
+    def __init__(self) -> None:
+        self.messages: list[AgentMessage] = []
+
+    def post_message(self, message: AgentMessage) -> None:
+        self.messages.append(message)
+
+    def get_messages(self, category: TaskCategory | None = None) -> list[AgentMessage]:
+        if category:
+            return [m for m in self.messages if m.category == category]
+        return self.messages
+
+    def format_for_prompt(self) -> str:
+        if not self.messages:
+            return ""
+        lines = ["--- Shared Collaboration Context ---"]
+        for msg in self.messages:
+            lines.append(f"[{msg.sender}]: {msg.content}")
+        return "\n".join(lines)
+
+
+class CollaborationAgent:
+    """Base interface for specialized collaboration agents."""
+    name: str
+    capabilities: list[TaskCategory]
+
+    async def execute(
+        self,
+        task: Task,
+        shared_context: CollaborationContext,
+        cancellation_token: CancellationToken,
+    ) -> AsyncGenerator[StreamEvent, None]:
+        raise NotImplementedError
+
+
+class BaseLLMCollaborationAgent(CollaborationAgent):
+    """Base class for LLM-backed specialized agents."""
+    def __init__(self, name: str, capabilities: list[TaskCategory], provider: LLMProvider, role_prompt: str, tool_registry: ToolRegistry | None = None):
+        self.name = name
+        self.capabilities = capabilities
+        self._agent = Agent(provider, system_prompt=role_prompt, tool_registry=tool_registry)
+
+    async def execute(
+        self,
+        task: Task,
+        shared_context: CollaborationContext,
+        cancellation_token: CancellationToken,
+    ) -> AsyncGenerator[StreamEvent, None]:
+        
+        cancellation_token.raise_if_cancelled()
+        
+        yield StreamEvent(event_type=StreamEventType.TOOL_START, content=f"[{self.name}] Starting task: {task.title}")
+        
+        prompt = f"Task Goal: {task.goal}\n\n{shared_context.format_for_prompt()}"
+        
+        try:
+            # We don't have a streaming respond in core Agent yet, so we just await respond
+            # In a real implementation we would stream it.
+            response = await self._agent.respond(AgentRequest(message=prompt))
+            shared_context.post_message(AgentMessage(
+                sender=self.name,
+                recipient=None,
+                category=self.capabilities[0],
+                content=response.content
+            ))
+            yield StreamEvent(event_type=StreamEventType.TOOL_COMPLETE, content=f"[{self.name}] Completed task: {task.title}")
+        except Exception as e:
+            yield StreamEvent(event_type=StreamEventType.TOOL_FAILED, content=f"[{self.name}] Failed task: {task.title}. Error: {e!s}")
+            raise
+
+
+class PlannerAgent(BaseLLMCollaborationAgent):
+    def __init__(self, provider: LLMProvider, tool_registry: ToolRegistry | None = None):
+        super().__init__(
+            name="Planner",
+            capabilities=[TaskCategory.PLANNING, TaskCategory.GENERAL],
+            provider=provider,
+            role_prompt="You are Pulse's Planner Agent. Analyze the request and shared context, and produce a detailed dependency graph and implementation plan.",
+            tool_registry=tool_registry,
+        )
+
+
+class SoftwareEngineerAgent(BaseLLMCollaborationAgent):
+    def __init__(self, provider: LLMProvider, tool_registry: ToolRegistry | None = None):
+        super().__init__(
+            name="SoftwareEngineer",
+            capabilities=[TaskCategory.CODING],
+            provider=provider,
+            role_prompt="You are Pulse's Software Engineer Agent. Turn the shared context and assigned task into a precise, robust implementation. Edit files as necessary.",
+            tool_registry=tool_registry,
+        )
+
+
+class ReviewerAgent(BaseLLMCollaborationAgent):
+    def __init__(self, provider: LLMProvider, tool_registry: ToolRegistry | None = None):
+        super().__init__(
+            name="Reviewer",
+            capabilities=[TaskCategory.REVIEW],
+            provider=provider,
+            role_prompt="You are Pulse's Reviewer Agent. Review the proposed solution for correctness, safety, regressions, and missing tests. Propose fixes if necessary.",
+            tool_registry=tool_registry,
+        )
+
+
+class TestingAgent(BaseLLMCollaborationAgent):
+    __test__ = False
+
+    def __init__(self, provider: LLMProvider, tool_registry: ToolRegistry | None = None):
+        super().__init__(
+            name="Tester",
+            capabilities=[TaskCategory.TESTING],
+            provider=provider,
+            role_prompt="You are Pulse's Testing Agent. Assess the review and implementation, write and run necessary tests, and ensure full coverage.",
+            tool_registry=tool_registry,
+        )
+
+# Alias for backward compatibility (to prevent breaking runtime.py and other imports)
+TesterAgent = TestingAgent
+
+
+class DocumentationAgent(BaseLLMCollaborationAgent):
+    def __init__(self, provider: LLMProvider, tool_registry: ToolRegistry | None = None):
+        super().__init__(
+            name="Documentation",
+            capabilities=[TaskCategory.DOCUMENTATION],
+            provider=provider,
+            role_prompt="You are Pulse's Documentation Agent. Ensure all docstrings, READMEs, and architecture docs are up-to-date with the latest code changes.",
+            tool_registry=tool_registry,
+        )
+
+
+class GitAgent(BaseLLMCollaborationAgent):
+    def __init__(self, provider: LLMProvider, tool_registry: ToolRegistry | None = None):
+        super().__init__(
+            name="GitAgent",
+            capabilities=[TaskCategory.GIT],
+            provider=provider,
+            role_prompt="You are Pulse's Git Agent. Manage version control, create branches, stage changes, and write semantic commit messages.",
+            tool_registry=tool_registry,
+        )
+
+
+class AgentManager:
+    """Orchestrates specialized agents, task assignments, and parallel execution."""
+
+    def __init__(
+        self,
+        task_manager: TaskManager,
+        agents: list[CollaborationAgent] | None = None,
+        context_manager: ContextManager | None = None,
+    ) -> None:
+        self.task_manager = task_manager
+        self.agents = agents or []
+        self.context_manager = context_manager
+        self.shared_context = CollaborationContext()
+
+    def register_agent(self, agent: CollaborationAgent) -> None:
+        self.agents.append(agent)
+
+    def _select_agent_for_task(self, task: Task) -> CollaborationAgent:
+        # Simple heuristic: categorize based on keywords in title/goal
+        goal_lower = f"{task.title} {task.goal}".lower()
+        
+        assigned_category = TaskCategory.GENERAL
+        if any(w in goal_lower for w in ["test", "verify", "validate"]):
+            assigned_category = TaskCategory.TESTING
+        elif any(w in goal_lower for w in ["review", "check", "lint"]):
+            assigned_category = TaskCategory.REVIEW
+        elif any(w in goal_lower for w in ["doc", "readme", "walkthrough"]):
+            assigned_category = TaskCategory.DOCUMENTATION
+        elif any(w in goal_lower for w in ["git", "commit", "branch", "pr "]):
+            assigned_category = TaskCategory.GIT
+        elif any(w in goal_lower for w in ["implement", "code", "write", "fix", "refactor"]):
+            assigned_category = TaskCategory.CODING
+        elif any(w in goal_lower for w in ["plan", "design", "architecture"]):
+            assigned_category = TaskCategory.PLANNING
+
+        # Find best agent
+        for agent in self.agents:
+            if assigned_category in agent.capabilities:
+                return agent
+        
+        # Fallback to SoftwareEngineer or first available
+        for agent in self.agents:
+            if TaskCategory.CODING in agent.capabilities:
+                return agent
+        
+        if self.agents:
+            return self.agents[0]
+            
+        raise RuntimeError("No agents available in AgentManager.")
+
+    async def run(self, prompt: str, context: list[str]) -> Any:
+        @dataclass(slots=True)
+        class AgentManagerResult:
+            final_response: str
+
+        for ctx in context:
+            self.shared_context.post_message(AgentMessage(
+                sender="System",
+                recipient=None,
+                category=TaskCategory.GENERAL,
+                content=ctx
+            ))
+            
+        task = await self.task_manager.create_task(goal=prompt, title=prompt[:45])
+        await self.task_manager.queue_task(task.id)
+        
+        async for event in self.execute_task_graph():
+            if event.event_type == StreamEventType.ERROR:
+                print(f"ERROR IN AGENT MANAGER: {event.content}")
+            
+        final_response = "No response generated."
+        agent_msgs = [m for m in self.shared_context.messages if m.sender != "System"]
+        if agent_msgs:
+            final_response = agent_msgs[-1].content
+            
+        return AgentManagerResult(final_response=final_response)
+
+    async def execute_task_graph(
+        self,
+        cancellation_token: CancellationToken | None = None
+    ) -> AsyncGenerator[StreamEvent, None]:
+        token = cancellation_token or CancellationToken()
+        
+        while True:
+            token.raise_if_cancelled()
+            
+            pending_tasks = self.task_manager.list_tasks(status=TaskStatus.QUEUED)
+            if not pending_tasks:
+                break
+                
+            # Filter tasks that have all dependencies met
+            ready_tasks = []
+            for t in pending_tasks:
+                unresolved = []
+                for dep_id in t.depends_on:
+                    dep_task = self.task_manager.get_task(dep_id)
+                    if dep_task and dep_task.status != TaskStatus.COMPLETED:
+                        unresolved.append(dep_id)
+                if not unresolved:
+                    ready_tasks.append(t)
+                    
+            if not ready_tasks:
+                yield StreamEvent(event_type=StreamEventType.ERROR, content="Deadlock detected: pending tasks exist but none are ready.")
+                break
+                
+            # Execute ready tasks in parallel
+            tasks_to_run = []
+            for task in ready_tasks:
+                agent = self._select_agent_for_task(task)
+                
+                tasks_to_run.append((task, agent))
+
+            # Since we need to yield StreamEvents, we can run them concurrently and merge the streams.
+            # A simple approach is to use a queue.
+            queue: asyncio.Queue[StreamEvent | Exception | None] = asyncio.Queue()
+            
+            async def agent_runner(t: Task, a: CollaborationAgent) -> None:
+                try:
+                    async def worker(leased_task: Task) -> str:
+                        async for event in a.execute(leased_task, self.shared_context, token):
+                            await queue.put(event)  # noqa: B023
+                        return "Agent execution finished"
+
+                    await self.task_manager.execute_task(t.id, worker)
+                # Intentionally broad to isolate execution boundaries and prevent crashes.
+                except Exception as e:  # noqa: BLE001
+                    await queue.put(e)  # noqa: B023
+
+            runners = [asyncio.create_task(agent_runner(t, a)) for t, a in tasks_to_run]
+            
+            async def watcher() -> None:
+                await asyncio.gather(*runners)  # noqa: B023
+                await queue.put(None)  # Sentinel to stop yielding  # noqa: B023
+                
+            watcher_task = asyncio.create_task(watcher())
+            
+            while True:
+                item = await queue.get()
+                if item is None:
+                    break
+                if isinstance(item, Exception):
+                    # We might want to handle conflict resolution here.
+                    # For now, we yield the error and continue.
+                    yield StreamEvent(event_type=StreamEventType.ERROR, content=f"Agent execution failed: {item!s}")
+                else:
+                    yield item
+                    
+            # Check for any unhandled exceptions in the watcher task
+            await watcher_task

pulse/audit.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+
+from pulse.sandbox.secrets import SecretScrubber
+from pulse.telemetry import get_correlation_id
+
+
+@dataclass(frozen=True)
+class AuditEntry:
+    schema_version: int = field(default=1, init=False)
+    timestamp: str
+    correlation_id: str
+    action: str
+    file: str
+    detail: str
+
+
+class AuditLog:
+    def __init__(self, path: Path, secrets: list[str] | None = None) -> None:
+        self.path = path
+        self.entries: list[AuditEntry] = []
+        self._scrubber = SecretScrubber(secrets)
+
+    def add_secret(self, secret: str | None) -> None:
+        if secret:
+            self._scrubber.add_secret(secret)
+
+    def record(self, action: str, file: str, detail: str) -> None:
+        entry = AuditEntry(
+            timestamp=datetime.now(UTC).isoformat(),
+            correlation_id=get_correlation_id(),
+            action=self._scrubber.redact(action),
+            file=self._scrubber.redact(file),
+            detail=self._scrubber.redact(detail),
+        )
+        self.entries.append(entry)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self.path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(asdict(entry), separators=(",", ":")) + "\n")
+        try:
+            os.chmod(self.path, 0o600)
+        except OSError:
+            pass
+
+    def print_summary(self) -> None:
+        if not self.entries:
+            return
+
+        from rich.console import Console
+        from rich.table import Table
+
+        from pulse.cli_ui import _box_style
+
+        console = Console()
+        table = Table(box=_box_style(), show_header=True, title="Session Audit Log")
+        table.add_column("Action", style="bold cyan")
+        table.add_column("File", style="yellow")
+        table.add_column("Detail", style="dim")
+
+        for entry in self.entries:
+            table.add_row(entry.action, entry.file, entry.detail)
+
+        console.print()
+        console.print(table)
+        console.print()