nullabot 1.0.1__py3-none-any.whl

nullabot/agents/claude_agent.py

@@ -0,0 +1,785 @@
+"""
+Claude Code Agent - Uses Claude Code CLI for autonomous work.
+
+Features:
+- Memory system (long-term + short-term like ChatGPT)
+- Agent handoff (designer sees what thinker did)
+- Cost tracking per project
+- 30-minute timeout for complex tasks
+- Clean folder structure (each agent has its own folder)
+"""
+
+import asyncio
+import json
+import os
+import signal
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.markdown import Markdown
+
+from nullabot.core.memory import ProjectMemory, UsageTracker, UserMemory
+from nullabot.core.rate_limiter import ClaudeCodeRateLimiter
+from nullabot.core.reliability import ExitDetector, ProgressTracker
+
+console = Console()
+
+# Timeout: 30 minutes (was 10)
+DEFAULT_TIMEOUT = 1800
+
+
+class ClaudeAgent:
+    """
+    Agent that uses Claude Code CLI directly.
+
+    Each agent works in its own subdirectory:
+      project/
+        thinker/    - Research & ideation output
+        designer/   - UI/UX design output
+        coder/      - Source code output
+        .nullabot/     - Shared state, memory, usage
+
+    Features:
+    - Uses your Claude Code subscription (no API key needed)
+    - Memory system for context sharing between agents
+    - Cost tracking per project
+    - Automatic handoff context from previous agents
+    """
+
+    PROMPTS = {
+        "thinker": """You are a Research & Ideation specialist working autonomously.
+
+Your task: {task}
+
+{context}
+
+## Your Workspace
+You are working in the `thinker/` folder of this project.
+Write all your output files here.
+{previous_work_hint}
+
+## Instructions
+1. Think deeply about this topic
+2. Research and explore multiple angles
+3. Write your findings to files:
+   - research/ - Research notes and findings
+   - ideas/ - Brainstormed ideas
+   - analysis/ - Detailed analysis
+   - recommendations.md - Final recommendations
+
+Work continuously. After each major step, summarize your progress.
+Focus on creating valuable, well-organized output files.
+
+IMPORTANT:
+- At the end of your response, include a STATUS line like:
+  STATUS: Working on [current task] | Files: [count] | Progress: [percentage]%
+- Also include a SUMMARY line with what you accomplished:
+  SUMMARY: [Brief description of what you did this cycle]""",
+
+        "designer": """You are a UI/UX Design specialist working autonomously.
+
+Your task: {task}
+
+{context}
+
+## Your Workspace
+You are working in the `designer/` folder of this project.
+Write all your output files here.
+
+{previous_work_hint}
+
+## Instructions
+1. FIRST: Read the thinker's work in `../thinker/` folder if it exists
+2. Analyze the design requirements based on research findings
+3. Create detailed component specifications
+4. Define design tokens and standards
+5. Write everything to files:
+   - components/ - Component specs (one file per component)
+   - patterns/ - UI pattern documentation
+   - tokens/ - Design tokens (colors, spacing, typography)
+   - design-system.md - Master design system document
+
+IMPORTANT:
+- At the end of your response, include a STATUS line like:
+  STATUS: Working on [current task] | Files: [count] | Progress: [percentage]%
+- Also include a SUMMARY line with what you accomplished:
+  SUMMARY: [Brief description of what you did this cycle]""",
+
+        "coder": """You are a Software Engineer working autonomously.
+
+Your task: {task}
+
+{context}
+
+## Your Workspace
+You are working in the `coder/` folder of this project.
+Write all your output files here.
+
+{previous_work_hint}
+
+## Instructions
+1. FIRST: Read previous work:
+   - `../thinker/` - Research and requirements
+   - `../designer/` - UI/UX specs and components
+2. Understand the requirements and design decisions already made
+3. Plan the architecture based on previous work
+4. Write clean, production-ready code
+5. Create comprehensive tests
+6. Organize files properly:
+   - src/ - Source code
+   - tests/ - Test files
+   - docs/ - Documentation
+   - ARCHITECTURE.md - Design decisions
+
+IMPORTANT:
+- At the end of your response, include a STATUS line like:
+  STATUS: Working on [current task] | Files: [count] | Progress: [percentage]%
+- Also include a SUMMARY line with what you accomplished:
+  SUMMARY: [Brief description of what you did this cycle]""",
+    }
+
+    def __init__(
+        self,
+        workspace: Path,
+        agent_type: str = "thinker",
+        model: str = "opus",
+        on_notify: Optional[Callable[[str, str, dict], Any]] = None,
+        timeout: int = DEFAULT_TIMEOUT,
+        user_id: int = None,
+        base_dir: Path = None,
+    ):
+        """
+        Initialize Claude Agent.
+
+        Args:
+            workspace: Project directory (not agent-specific)
+            agent_type: Type of agent (thinker, designer, coder)
+            model: Model to use (opus, sonnet, haiku)
+            on_notify: Callback for notifications (event_type, message, data)
+            timeout: Timeout in seconds (default 30 min)
+            user_id: User ID for user-level memory
+            base_dir: Base directory (nullabot repo root) for user memory
+        """
+        # Project-level paths
+        self.project_dir = workspace.resolve()
+        self.project_dir.mkdir(parents=True, exist_ok=True)
+
+        # Agent-specific workspace (project/agent_type/)
+        self.agent_type = agent_type
+        self.workspace = self.project_dir / agent_type
+        self.workspace.mkdir(parents=True, exist_ok=True)
+
+        self.model = model
+        self.on_notify = on_notify
+        self.timeout = timeout
+        self.user_id = user_id
+
+        # Shared state at project level (.nullabot/)
+        self.state_dir = self.project_dir / ".nullabot"
+        self.state_dir.mkdir(exist_ok=True)
+
+        # Agent-specific state file
+        self.state_file = self.state_dir / f"state_{agent_type}.json"
+        self.log_file = self.state_dir / f"log_{agent_type}.jsonl"
+
+        # Base dir (nullabot repo root, default: grandparent of project)
+        self.base_dir = base_dir or self.project_dir.parent.parent
+
+        # Shared memory and usage at project level
+        self.memory = ProjectMemory(self.project_dir)
+        self.usage = UsageTracker(self.project_dir, self.base_dir)
+
+        # User-level memory (at {base_dir}/users/{id}/)
+        self.user_memory = UserMemory(self.base_dir, user_id) if user_id else None
+
+        # Control flags
+        self._should_stop = False
+        self._is_running = False
+
+        # Rate limiter - tracks 5-hour and weekly limits
+        self.rate_limiter = ClaudeCodeRateLimiter(
+            plan="max_200",
+            auto_wait=False,  # Don't auto-wait, exit gracefully instead
+        )
+
+        # Exit detector - tracks when to stop
+        self.exit_detector = ExitDetector(
+            max_cycles=100,
+            max_cycles_no_progress=5,
+        )
+
+        # Progress tracker
+        self.progress_tracker = ProgressTracker()
+
+        # Signal handlers
+        signal.signal(signal.SIGINT, self._handle_signal)
+        signal.signal(signal.SIGTERM, self._handle_signal)
+
+    def _handle_signal(self, signum: int, frame: Any) -> None:
+        """Handle shutdown signals."""
+        console.print("\n[yellow]Stopping agent gracefully...[/yellow]")
+        self._should_stop = True
+        self._notify("stop_requested", "🛑 Stop requested, saving state...")
+
+    async def _notify(self, event: str, message: str, data: dict = None) -> None:
+        """Send notification via callback."""
+        if self.on_notify:
+            try:
+                result = self.on_notify(event, message, data or {})
+                if asyncio.iscoroutine(result):
+                    await result
+            except Exception as e:
+                console.print(f"[dim]Notification error: {e}[/dim]")
+
+    def _load_state(self) -> dict:
+        """Load agent state from disk."""
+        if self.state_file.exists():
+            try:
+                return json.loads(self.state_file.read_text())
+            except:
+                pass
+        return {
+            "task": None,
+            "status": "idle",
+            "cycles": 0,
+            "files_created": [],
+            "last_checkpoint": None,
+            "started_at": None,
+            "total_time_seconds": 0,
+        }
+
+    def _save_state(self, state: dict) -> None:
+        """Save agent state to disk."""
+        state["updated_at"] = datetime.now().isoformat()
+        self.state_file.write_text(json.dumps(state, indent=2))
+
+    def _log(self, event: str, data: dict = None) -> None:
+        """Append to log file."""
+        entry = {
+            "timestamp": datetime.now().isoformat(),
+            "event": event,
+            "data": data or {},
+        }
+        with open(self.log_file, "a") as f:
+            f.write(json.dumps(entry) + "\n")
+
+    def _count_files(self) -> tuple[int, list[str]]:
+        """Count files in workspace (excluding .nullabot)."""
+        files = []
+        for f in self.workspace.rglob("*"):
+            if f.is_file() and ".nullabot" not in str(f):
+                rel = str(f.relative_to(self.workspace))
+                files.append(rel)
+        return len(files), files[:20]
+
+    def _extract_status(self, response: str) -> Optional[str]:
+        """Extract STATUS line from response."""
+        for line in response.split("\n"):
+            if line.strip().startswith("STATUS:"):
+                return line.strip()
+        return None
+
+    def _extract_summary(self, response: str) -> Optional[str]:
+        """Extract SUMMARY line from response."""
+        for line in response.split("\n"):
+            if line.strip().startswith("SUMMARY:"):
+                return line.strip().replace("SUMMARY:", "").strip()
+        # Fallback: first 200 chars
+        return response[:200].replace("\n", " ").strip()
+
+    def _make_progress_bar(self, percentage: float, width: int = 10) -> str:
+        """Create a text progress bar for notifications."""
+        filled = int(width * percentage / 100)
+        empty = width - filled
+        bar = "█" * filled + "░" * empty
+        return f"[{bar}]"
+
+    async def _run_claude_async(
+        self,
+        prompt: str,
+    ) -> tuple[str, bool]:
+        """Run Claude Code CLI asynchronously."""
+        cmd = [
+            "claude",
+            "-p",
+            "--output-format", "text",
+            "--model", self.model,
+            "--max-turns", "50",
+            "--dangerously-skip-permissions",
+            prompt,
+        ]
+
+        try:
+            process = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                cwd=str(self.workspace),
+                env={
+                    **os.environ,
+                    "CLAUDE_CODE_ENTRYPOINT": "nullabot",
+                },
+            )
+
+            stdout, stderr = await asyncio.wait_for(
+                process.communicate(),
+                timeout=self.timeout,
+            )
+
+            output = stdout.decode().strip()
+            if process.returncode != 0:
+                error = stderr.decode() or "Unknown error"
+                return f"Error: {error}", False
+
+            return output, True
+
+        except asyncio.TimeoutError:
+            timeout_min = self.timeout // 60
+            return f"Error: Claude timed out after {timeout_min} minutes", False
+        except Exception as e:
+            return f"Error: {str(e)}", False
+
+    def _get_previous_work_hint(self) -> str:
+        """Get hint about where to find previous agents' work."""
+        hints = []
+
+        # Check what other agents have done
+        if self.agent_type == "designer":
+            thinker_dir = self.project_dir / "thinker"
+            if thinker_dir.exists() and any(thinker_dir.iterdir()):
+                hints.append("📂 Thinker's research is available in `../thinker/`")
+
+        elif self.agent_type == "coder":
+            thinker_dir = self.project_dir / "thinker"
+            designer_dir = self.project_dir / "designer"
+
+            if thinker_dir.exists() and any(thinker_dir.iterdir()):
+                hints.append("📂 Thinker's research is available in `../thinker/`")
+            if designer_dir.exists() and any(designer_dir.iterdir()):
+                hints.append("📂 Designer's specs are available in `../designer/`")
+
+        if hints:
+            return "## Previous Work Available\n" + "\n".join(hints)
+        return ""
+
+    def get_system_prompt(self, task: str) -> str:
+        """Get system prompt for agent type with memory context."""
+        template = self.PROMPTS.get(self.agent_type, self.PROMPTS["thinker"])
+
+        # Build user-level context (global preferences across all projects)
+        user_context = self.user_memory.build_user_context() if self.user_memory else ""
+
+        # Build project-level context
+        project_context = self.memory.build_context_for_agent(self.agent_type)
+
+        # Combine contexts
+        context_parts = []
+        if user_context:
+            context_parts.append(f"## User Preferences (global)\n\n{user_context}")
+        if project_context:
+            context_parts.append(f"## Project Context (from previous work)\n\n{project_context}")
+
+        if context_parts:
+            context = "\n\n".join(context_parts)
+        else:
+            context = "## Project Context\n\nThis is a new project. No previous work exists yet."
+
+        # Add hints about where previous work is located
+        previous_work_hint = self._get_previous_work_hint()
+
+        return template.format(
+            task=task,
+            context=context,
+            previous_work_hint=previous_work_hint
+        )
+
+    async def start(self, task: str, continuous: bool = True) -> None:
+        """
+        Start the agent on a task.
+
+        Args:
+            task: What to work on
+            continuous: Keep working in cycles until stopped
+        """
+        if self._is_running:
+            console.print("[red]Agent already running[/red]")
+            return
+
+        self._is_running = True
+        self._should_stop = False
+        start_time = datetime.now()
+
+        # Load or initialize state
+        state = self._load_state()
+
+        # Check for resume
+        can_resume = (
+            state.get("task") == task and
+            (state.get("last_checkpoint") or state.get("cycles", 0) > 0)
+        )
+
+        if can_resume:
+            console.print("[green]Resuming from checkpoint...[/green]")
+            await self._notify("resume", f"🔄 Resuming `{self.workspace.name}` from cycle {state.get('cycles', 0)}")
+
+            checkpoint = state.get("last_checkpoint", "")
+            if checkpoint:
+                resume_context = f"\n\nPrevious progress:\n{checkpoint}\n\nContinue from where you left off."
+            else:
+                resume_context = "\n\nContinue working on this task. You've made some progress already."
+
+            state["status"] = "running"
+        else:
+            resume_context = ""
+            state = {
+                "task": task,
+                "agent_type": self.agent_type,
+                "status": "running",
+                "cycles": 0,
+                "files_created": [],
+                "started_at": datetime.now().isoformat(),
+                "last_checkpoint": None,
+                "total_time_seconds": 0,
+            }
+            # Note in short-term memory
+            self.memory.note(f"Started {self.agent_type} agent with task: {task[:100]}")
+
+            # Extract rules from user's task prompt
+            if self.user_memory:
+                self.user_memory.extract_from_response(task)
+
+        self._save_state(state)
+        self._log("started", {"task": task})
+
+        # Get usage summary for notification
+        usage_summary = self.usage.get_summary()
+
+        # Send start notification
+        await self._notify(
+            "start",
+            f"🚀 *{self.agent_type.upper()}* started on `{self.workspace.name}`\n\n"
+            f"📋 *Task:* {task[:200]}\n"
+            f"🤖 *Model:* {self.model}\n"
+            f"💰 *Project cost so far:* ${usage_summary['total_cost_usd']:.2f}",
+            {"task": task, "model": self.model}
+        )
+
+        console.print(Panel(
+            f"[bold green]Starting {self.agent_type} agent[/bold green]\n\n"
+            f"[bold]Task:[/bold] {task}\n"
+            f"[bold]Workspace:[/bold] {self.workspace}\n"
+            f"[bold]Model:[/bold] {self.model}\n"
+            f"[bold]Timeout:[/bold] {self.timeout // 60} minutes\n"
+            f"[bold]Project cost:[/bold] ${usage_summary['total_cost_usd']:.2f}\n\n"
+            "[dim]Press Ctrl+C to stop gracefully[/dim]",
+            title="Nullabot",
+        ))
+
+        # Build initial prompt with memory context
+        system_prompt = self.get_system_prompt(task)
+        current_prompt = system_prompt + resume_context
+
+        cycle = state.get("cycles", 0)
+        errors_in_row = 0
+
+        try:
+            while not self._should_stop:
+                cycle += 1
+                cycle_start = datetime.now()
+
+                console.print(f"\n[bold blue]═══ Cycle {cycle} ═══[/bold blue]\n")
+
+                # Notify cycle start
+                await self._notify(
+                    "cycle_start",
+                    f"🔄 *Cycle {cycle}* starting...",
+                    {"cycle": cycle}
+                )
+
+                # Run Claude
+                response, success = await self._run_claude_async(current_prompt)
+
+                cycle_duration = (datetime.now() - cycle_start).total_seconds()
+
+                # Track usage
+                usage_info = self.usage.record_cycle(
+                    model=self.model,
+                    agent_type=self.agent_type,
+                    input_tokens=len(current_prompt) // 4,  # Rough estimate
+                    output_tokens=len(response) // 4 if success else 0,
+                    duration_seconds=cycle_duration,
+                )
+
+                if not success:
+                    errors_in_row += 1
+                    console.print(f"[red]{response}[/red]")
+                    self._log("error", {"message": response})
+
+                    # Check if this is a rate limit error (5-hour limit reached)
+                    if self.rate_limiter.is_limit_error(response):
+                        is_limit, wait_time = self.rate_limiter.record_error(response)
+
+                        # Mark the GLOBAL 5-hour window as reached
+                        self.usage.mark_limit_reached()
+
+                        if wait_time > 0:
+                            wait_hours = wait_time / 3600
+                            wait_minutes = (wait_time % 3600) / 60
+
+                            await self._notify(
+                                "rate_limit",
+                                f"⏰ *5-hour limit reached!*\n\n"
+                                f"Claude Code subscription limit hit at 100%.\n"
+                                f"Window resets in ~{wait_hours:.1f}h ({wait_minutes:.0f}m)\n\n"
+                                f"🔄 *Cycles completed:* {cycle}\n"
+                                f"💰 *Cost this session:* ${self.usage.get_summary()['total_cost_usd']:.2f}\n\n"
+                                f"Agent will stop. Run again after the window resets.",
+                                {"cycle": cycle, "wait_time": wait_time}
+                            )
+                        else:
+                            await self._notify(
+                                "rate_limit",
+                                f"⏰ *Rate limit reached!*\n\n"
+                                f"`{response[:200]}`\n\n"
+                                f"Agent stopping gracefully.",
+                                {"cycle": cycle}
+                            )
+
+                        console.print(f"\n[yellow]Rate limit reached. Stopping agent.[/yellow]")
+                        break
+
+                    # Notify error
+                    await self._notify(
+                        "error",
+                        f"❌ *Error in cycle {cycle}:*\n`{response[:300]}`",
+                        {"cycle": cycle, "error": response}
+                    )
+
+                    if "not found" in response.lower():
+                        await self._notify("fatal", "💀 Claude CLI not found! Install it first.")
+                        break
+
+                    # "Reached max turns" is not really an error - it's normal completion
+                    if "max turns" in response.lower() or "reached max" in response.lower():
+                        console.print(f"[yellow]Claude reached max turns limit. Cycle complete.[/yellow]")
+                        errors_in_row = 0  # Don't count as error
+                        # Continue to next cycle
+                        await asyncio.sleep(5)
+                        continue
+
+                    if errors_in_row >= 3:
+                        await self._notify("fatal", f"💀 Too many errors ({errors_in_row}). Stopping.")
+                        break
+
+                    await asyncio.sleep(10)
+                    continue
+
+                errors_in_row = 0
+
+                # Record success for rate limiter tracking
+                self.rate_limiter.record_success(self.model)
+
+                # Check exit conditions (max cycles, no progress, etc.)
+                should_exit, exit_reason = self.exit_detector.should_exit(
+                    current_cycle=cycle,
+                    cycles_no_progress=0,  # Will be updated below
+                    progress_tracker=self.progress_tracker,
+                )
+                if should_exit:
+                    await self._notify(
+                        "exit_condition",
+                        f"🛑 *Exit condition reached:* `{exit_reason}`\n\n"
+                        f"Completed {cycle} cycles.",
+                        {"cycle": cycle, "reason": exit_reason}
+                    )
+                    console.print(f"\n[yellow]Exit condition: {exit_reason}[/yellow]")
+                    break
+
+                # Display response (truncated)
+                console.print(Markdown(response[:2000]))
+                self._log("response", {"content": response[:1000]})
+
+                # Extract and save summary to memory
+                summary = self._extract_summary(response)
+                self.memory.note(f"Cycle {cycle}: {summary}")
+                self.memory.extract_memories_from_response(response)
+
+                # Extract user preferences to global memory
+                if self.user_memory:
+                    self.user_memory.extract_from_response(response)
+
+                # Count files
+                file_count, file_list = self._count_files()
+
+                # Track file purposes (basic)
+                for f in file_list:
+                    if f not in self.memory.get_file_purposes():
+                        # Try to infer purpose from path
+                        if "research" in f.lower():
+                            self.memory.set_file_purpose(f, "Research findings")
+                        elif "design" in f.lower() or "component" in f.lower():
+                            self.memory.set_file_purpose(f, "Design specifications")
+                        elif "src" in f.lower() or f.endswith(".py") or f.endswith(".js"):
+                            self.memory.set_file_purpose(f, "Source code")
+
+                # Extract status line
+                status_line = self._extract_status(response) or f"Cycle {cycle} complete"
+
+                # Update state
+                state["cycles"] = cycle
+                state["last_checkpoint"] = response[:2000]
+                state["status"] = "running"
+                state["files_created"] = file_list
+                state["total_time_seconds"] = (datetime.now() - start_time).total_seconds()
+                self._save_state(state)
+
+                # Send cycle complete notification with window usage
+                window_pct = usage_info.get('window_usage_pct', 0)
+                window_bar = self._make_progress_bar(window_pct)
+
+                await self._notify(
+                    "cycle_complete",
+                    f"✅ *Cycle {cycle}* complete ({cycle_duration:.0f}s)\n\n"
+                    f"📁 *Files:* {file_count}\n"
+                    f"⏱ *5hr window:* {window_bar} {window_pct:.0f}%\n"
+                    f"💰 *Est. cost:* ${usage_info['cycle_cost']:.2f} (Total: ${usage_info['total_cost']:.2f})\n"
+                    f"📊 {status_line}\n\n"
+                    f"💬 _{summary[:200]}_",
+                    {
+                        "cycle": cycle,
+                        "duration": cycle_duration,
+                        "file_count": file_count,
+                        "files": file_list[:10],
+                        "summary": summary,
+                        "cost": usage_info,
+                    }
+                )
+
+                # Warn if approaching 5-hour limit
+                if window_pct >= 90:
+                    await self._notify(
+                        "limit_warning",
+                        f"⚠️ *Warning:* 5-hour window at {window_pct:.0f}%!\n"
+                        f"Agent will stop soon to prevent hitting the limit.",
+                        {"window_pct": window_pct}
+                    )
+                    if window_pct >= 95:
+                        console.print(f"\n[yellow]Approaching 5-hour limit ({window_pct:.0f}%). Stopping gracefully.[/yellow]")
+                        break
+
+                if not continuous:
+                    break
+
+                # Check for completion signals
+                completion_signals = ["task complete", "all done", "finished", "nothing left"]
+                if any(sig in response.lower() for sig in completion_signals):
+                    await self._notify(
+                        "maybe_complete",
+                        f"🤔 Agent thinks it might be done. Continue? (auto-continues in 30s)",
+                        {"cycle": cycle}
+                    )
+
+                # Prepare next cycle prompt (include recent memory context)
+                recent_context = "\n".join(self.memory.get_short_term_context(3))
+                current_prompt = f"""Continue working on: {task}
+
+Recent activity:
+{recent_context}
+
+Your previous output was:
+{response[:1500]}
+
+Continue making progress. Create or update files as needed.
+If you've completed everything, summarize what you accomplished.
+
+Remember to include STATUS and SUMMARY lines at the end."""
+
+                # Brief pause between cycles
+                console.print("\n[dim]Next cycle in 5 seconds...[/dim]")
+                await asyncio.sleep(5)
+
+        except Exception as e:
+            console.print(f"[red]Error: {e}[/red]")
+            self._log("error", {"message": str(e)})
+            await self._notify("error", f"❌ *Fatal error:*\n`{str(e)[:300]}`")
+
+        finally:
+            total_time = (datetime.now() - start_time).total_seconds()
+            file_count, file_list = self._count_files()
+
+            # Save final summary to memory for next agent
+            final_summary = f"Completed {cycle} cycles. Created {file_count} files. Last status: {status_line if 'status_line' in dir() else 'N/A'}"
+            self.memory.save_agent_summary(self.agent_type, final_summary)
+            self.memory.remember(f"{self.agent_type} completed task: {task[:100]}", category="milestone")
+
+            # Update user memory with project summary (global)
+            if self.user_memory:
+                project_name = self.project_dir.name
+                self.user_memory.update_project_summary(
+                    project_name,
+                    f"{self.agent_type}: {task[:100]} ({cycle} cycles, {file_count} files)"
+                )
+
+            state["status"] = "paused" if self._should_stop else "completed"
+            state["total_time_seconds"] = total_time
+            state["files_created"] = file_list
+            self._save_state(state)
+            self._log("stopped", {"cycles": cycle, "total_time": total_time})
+            self._is_running = False
+
+            # Get final usage
+            usage_summary = self.usage.get_summary()
+
+            # Send completion notification
+            hours = int(total_time // 3600)
+            minutes = int((total_time % 3600) // 60)
+            time_str = f"{hours}h {minutes}m" if hours else f"{minutes}m"
+
+            window_pct = usage_summary.get('window_usage_pct', 0)
+            window_hours = usage_summary.get('window_hours', 0)
+            window_bar = self._make_progress_bar(window_pct)
+
+            await self._notify(
+                "complete",
+                f"🏁 *Agent finished!*\n\n"
+                f"📁 *Project:* `{self.workspace.name}`\n"
+                f"🔄 *Cycles:* {cycle}\n"
+                f"⏱ *Duration:* {time_str}\n"
+                f"📂 *Files created:* {file_count}\n"
+                f"⏱ *5hr window:* {window_bar} {window_pct:.0f}% ({window_hours:.1f}h used)\n"
+                f"💰 *Est. cost:* ${usage_summary['total_cost_usd']:.2f}\n\n"
+                f"*Files:*\n" + "\n".join(f"• `{f}`" for f in file_list[:10]),
+                {
+                    "cycles": cycle,
+                    "duration": total_time,
+                    "file_count": file_count,
+                    "files": file_list,
+                    "cost": usage_summary,
+                }
+            )
+
+            console.print(f"\n[green]Agent stopped. Completed {cycle} cycles in {time_str}.[/green]")
+            console.print(f"[dim]Workspace: {self.workspace}[/dim]")
+            console.print(f"[dim]5-hour window: {window_pct:.0f}% used ({window_hours:.1f}h)[/dim]")
+            console.print(f"[dim]Est. cost: ${usage_summary['total_cost_usd']:.2f}[/dim]")
+
+    def stop(self) -> None:
+        """Request agent to stop."""
+        self._should_stop = True
+
+    def status(self) -> dict:
+        """Get current agent status."""
+        state = self._load_state()
+        file_count, files = self._count_files()
+        state["current_file_count"] = file_count
+        state["files"] = files
+        state["usage"] = self.usage.get_summary()
+        state["memory"] = {
+            "long_term_count": len(self.memory.get_long_term_memories()),
+            "short_term_count": len(self.memory.get_short_term_context()),
+            "agent_summaries": list(self.memory.get_all_agent_summaries().keys()),
+        }
+        return state