Implement initial project structure and features for Automaker application, including environment setup, auto mode services, and session management. Update port configurations to 3007 and add new UI components for enhanced user interaction.

2026-02-03 21:03:08 +00:00 · 2025-12-08 21:11:00 -05:00
parent 3c8e786f29
commit 9392422d35
67 changed files with 16275 additions and 696 deletions
--- a/app/docs/AGENT_ARCHITECTURE.md
+++ b/app/docs/AGENT_ARCHITECTURE.md
@@ -0,0 +1,285 @@
+# Agent Architecture - Surviving Next.js Restarts
+
+## Problem Statement
+
+When using the Automaker app to iterate on itself:
+
+1. Agent modifies code files
+2. Next.js hot-reloads and restarts
+3. API routes are killed
+4. Agent conversation is lost
+
+## Solution: Electron Main Process Agent
+
+The agent now runs in the **Electron main process** instead of Next.js API routes. This provides:
+
+- ✅ **Survives Next.js restarts** - Main process is independent of renderer
+- ✅ **Persistent state** - Conversations saved to disk automatically
+- ✅ **Real-time streaming** - IPC events for live updates
+- ✅ **Session recovery** - Reconnects automatically after restart
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────┐
+│   Electron Main Process                 │
+│   ┌───────────────────────────────┐     │
+│   │  Agent Service                │     │
+│   │  - Manages sessions           │     │
+│   │  - Runs Claude Agent SDK      │     │
+│   │  - Persists to disk           │     │
+│   │  - Streams via IPC            │     │
+│   └───────────────────────────────┘     │
+└──────────────┬──────────────────────────┘
+               │ IPC (survives restarts)
+┌──────────────┴──────────────────────────┐
+│   Electron Renderer (Next.js)           │
+│   ┌───────────────────────────────┐     │
+│   │  React Frontend               │     │
+│   │  - useElectronAgent hook      │     │
+│   │  - Auto-reconnects            │     │
+│   │  - Real-time updates          │     │
+│   └───────────────────────────────┘     │
+└─────────────────────────────────────────┘
+```
+
+## Key Components
+
+### 1. Agent Service (`electron/agent-service.js`)
+
+The core service running in the Electron main process:
+
+- **Session Management**: Tracks multiple conversations by session ID
+- **State Persistence**: Saves conversations to `userData/agent-sessions/*.json`
+- **Streaming**: Sends real-time updates to renderer via IPC
+- **Tool Support**: Full Read/Write/Edit/Bash/Grep/Glob capabilities
+- **Error Recovery**: Continues after errors, saves state
+
+### 2. IPC Handlers (`electron/main.js`)
+
+Electron main process handlers:
+
+- `agent:start` - Initialize or resume a session
+- `agent:send` - Send a message (returns immediately)
+- `agent:getHistory` - Retrieve conversation history
+- `agent:stop` - Stop current execution
+- `agent:clear` - Clear conversation
+- `agent:stream` - Event emitted for streaming updates
+
+### 3. Preload Bridge (`electron/preload.js`)
+
+Secure IPC bridge exposed to renderer:
+
+```javascript
+window.electronAPI.agent.start(sessionId, workingDir);
+window.electronAPI.agent.send(sessionId, message, workingDir);
+window.electronAPI.agent.onStream(callback);
+```
+
+### 4. React Hook (`src/hooks/use-electron-agent.ts`)
+
+Easy-to-use React hook:
+
+```typescript
+const {
+  messages, // Conversation history
+  isProcessing, // Agent is working
+  isConnected, // Session initialized
+  sendMessage, // Send user message
+  stopExecution, // Stop current task
+  clearHistory, // Clear conversation
+  error, // Error state
+} = useElectronAgent({
+  sessionId: "project_xyz",
+  workingDirectory: "/path/to/project",
+  onToolUse: (tool) => console.log("Using:", tool),
+});
+```
+
+### 5. Frontend Component (`src/components/views/agent-view.tsx`)
+
+Updated to use IPC instead of HTTP:
+
+- Generates session ID from project path
+- Auto-reconnects on mount
+- Shows tool usage in real-time
+- Displays connection status
+
+## Data Flow
+
+### Sending a Message
+
+1. User types message in React UI
+2. `sendMessage()` calls `window.electronAPI.agent.send()`
+3. IPC handler in main process receives message
+4. Agent service starts processing
+5. Main process streams updates via `agent:stream` events
+6. React hook receives events and updates UI
+7. Conversation saved to disk
+
+### Surviving a Restart
+
+1. Agent is modifying code → Next.js restarts
+2. React component unmounts
+3. **Main process keeps running** (agent continues)
+4. React component remounts after restart
+5. Calls `agent:start` with same session ID
+6. Main process returns full conversation history
+7. Subscribes to `agent:stream` events
+8. UI shows complete conversation + live updates
+
+## Session Storage
+
+Sessions are stored in:
+
+```
+<userData>/agent-sessions/<sessionId>.json
+```
+
+Each session file contains:
+
+```json
+[
+  {
+    "id": "msg_1234_abc",
+    "role": "user",
+    "content": "Add a new feature...",
+    "timestamp": "2024-12-07T12:00:00.000Z"
+  },
+  {
+    "id": "msg_1235_def",
+    "role": "assistant",
+    "content": "I'll help you add that feature...",
+    "timestamp": "2024-12-07T12:00:05.000Z"
+  }
+]
+```
+
+## Session ID Generation
+
+Session IDs are generated from project paths:
+
+```typescript
+const sessionId = `project_${projectPath.replace(/[^a-zA-Z0-9]/g, "_")}`;
+```
+
+This ensures:
+
+- Each project has its own conversation
+- Conversations persist across app restarts
+- Multiple projects can run simultaneously
+
+## Streaming Events
+
+The agent emits these event types:
+
+### `message`
+
+User message added to conversation
+
+### `stream`
+
+Assistant response streaming (updates in real-time)
+
+### `tool_use`
+
+Agent is using a tool (Read, Write, Edit, etc.)
+
+### `complete`
+
+Agent finished processing
+
+### `error`
+
+Error occurred during processing
+
+## Configuration
+
+The agent is configured with:
+
+```javascript
+{
+  model: "claude-opus-4-5-20251101",
+  maxTurns: 20,
+  cwd: workingDirectory,
+  allowedTools: [
+    "Read", "Write", "Edit", "Glob", "Grep",
+    "Bash", "WebSearch", "WebFetch"
+  ],
+  permissionMode: "acceptEdits",  // Auto-approve file edits
+  sandbox: {
+    enabled: true,                // Sandboxed bash execution
+    autoAllowBashIfSandboxed: true
+  }
+}
+```
+
+## Benefits
+
+### For Self-Iteration
+
+Now you can ask the agent to modify Automaker itself:
+
+```
+User: "Add a dark mode toggle to the settings"
+Agent: *modifies files*
+→ Next.js restarts
+→ Agent continues working
+→ UI reconnects automatically
+→ Shows full conversation history
+```
+
+### For Long-Running Tasks
+
+The agent can work on complex tasks that take multiple turns:
+
+```
+User: "Implement authentication with GitHub OAuth"
+Agent:
+  1. Creates auth API routes
+  2. Next.js restarts
+  3. Agent continues: Adds middleware
+  4. Next.js restarts again
+  5. Agent continues: Updates UI components
+  6. All changes tracked, conversation preserved
+```
+
+## Testing
+
+To test the architecture:
+
+1. Open a project in Automaker
+2. Ask the agent to modify a file in `src/`
+3. Watch Next.js restart
+4. Verify the conversation continues
+5. Check that history is preserved
+6. Restart the entire Electron app
+7. Verify conversation loads from disk
+
+## Troubleshooting
+
+### "Electron API not available"
+
+- Make sure you're running in Electron, not browser
+- Check `window.isElectron` is `true`
+
+### Session not persisting
+
+- Check userData directory exists
+- Verify write permissions
+- Look for errors in Electron console
+
+### Next.js restart kills agent
+
+- Verify agent service is in `electron/main.js`
+- Check IPC handlers are registered
+- Ensure not using HTTP `/api/chat` route
+
+## Future Enhancements
+
+- [ ] Multiple concurrent sessions
+- [ ] Export conversation history
+- [ ] Undo/redo for agent actions
+- [ ] Progress bars for long-running tasks
+- [ ] Voice input/output
+- [ ] Agent memory across sessions