@prmichaelsen/task-mcp 0.2.0

package/agent/design/acp-task-execution-requirements.md

@@ -0,0 +1,555 @@
+# ACP Task Execution System for agentbase.me (MCP Server Architecture)
+
+**Concept**: Port ACP-style autonomous task execution from Roo Code to agentbase.me using MCP server architecture
+**Created**: 2026-02-16
+**Last Updated**: 2026-02-16
+**Status**: Design Specification
+
+---
+
+## Overview
+
+This design document specifies the requirements for porting the Agent Context Protocol (ACP) task execution system from Roo Code to agentbase.me using an **MCP server-first architecture**. The goal is to enable long-running, autonomous task execution where agents work through structured milestones and tasks independently in the background, separate from conversational threads.
+
+**Core Principle**: Unlike Roo Code's optimistic completion model (where agents ask for approval before proceeding), agentbase.me will use a **pessimistic execution model** where agents continuously work through all milestones and tasks until explicitly paused or all work is complete.
+
+**Architecture Principle**: Task management tools are exposed via a **separate MCP server** following the [MCP Server Bootstrap Pattern](https://github.com/prmichaelsen/remember-mcp/blob/main/agent/patterns/bootstrap.md), not embedded in agentbase.me codebase.
+
+---
+
+## Problem Statement
+
+Currently, agentbase.me supports only conversational chat interactions. Users cannot:
+
+1. **Create long-running tasks** that execute independently of the main conversation
+2. **Track structured progress** through milestones and sub-tasks
+3. **Resume work** on tasks across sessions
+4. **Monitor background execution** while continuing other conversations
+5. **Leverage ACP methodology** for systematic project development
+
+This limits agentbase.me to short, interactive conversations rather than complex, multi-step project work.
+
+---
+
+## Solution
+
+Implement a **Task Execution System** with **MCP Server Architecture** that:
+
+1. **Creates separate "task" conversation types** alongside regular chat conversations
+2. **Exposes task management tools via MCP server** (separate project)
+3. **Exposes REST API endpoints** for web UI operations (dual interface)
+4. **Executes tasks autonomously** in the background using ACP methodology
+5. **Persists task state** in Firestore for resumability
+6. **Sends progress updates** to the task thread as work proceeds
+7. **Respects user control** via pause/resume/stop controls
+8. **Shares business logic** between MCP tools and REST endpoints
+
+**See Also**: [REST API Integration Design](rest-api-integration.md) for detailed REST endpoint specifications.
+
+---
+
+## Architecture: MCP Server-First Approach
+
+### System Components
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      agentbase.me                           │
+│                                                             │
+│  ┌──────────────┐         ┌─────────────────┐             │
+│  │   Web UI     │────────▶│   API Routes    │             │
+│  │              │         │  (UI Operations)│             │
+│  └──────────────┘         └─────────────────┘             │
+│         │                          │                       │
+│         │                          ▼                       │
+│         │                   ┌─────────────┐               │
+│         │                   │  Firestore  │               │
+│         │                   │  (Tasks DB) │               │
+│         │                   └─────────────┘               │
+│         │                          ▲                       │
+│         │                          │                       │
+│         ▼                          │                       │
+│  ┌──────────────┐                 │                       │
+│  │  WebSocket   │                 │                       │
+│  │  (Updates)   │                 │                       │
+│  └──────────────┘                 │                       │
+│         ▲                          │                       │
+│         │                          │                       │
+│         │                          │                       │
+│  ┌──────────────────────────────────────┐                │
+│  │         Agent (Chat)                  │                │
+│  │                                       │                │
+│  │  ┌────────────────────────────────┐  │                │
+│  │  │   MCP Client                   │  │                │
+│  │  │   (connects to task-mcp)       │  │                │
+│  │  └────────────────────────────────┘  │                │
+│  └──────────────────────────────────────┘                │
+│         │                                                  │
+└─────────┼──────────────────────────────────────────────────┘
+          │
+          │ MCP Protocol
+          │
+          ▼
+┌─────────────────────────────────────────────────────────────┐
+│              task-mcp (Separate MCP Server)                 │
+│                                                             │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │  MCP Server (stdio/SSE transport)                    │  │
+│  └──────────────────────────────────────────────────────┘  │
+│         │                                                   │
+│         ▼                                                   │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │  Task Management Tools                               │  │
+│  │  - task_get_status                                   │  │
+│  │  - task_create_milestone                             │  │
+│  │  - task_create_task                                  │  │
+│  │  - task_complete_task                                │  │
+│  │  - task_update_progress                              │  │
+│  │  - task_init                                         │  │
+│  │  - task_sync                                         │  │
+│  │  - task_generate_report                              │  │
+│  │  - task_validate                                     │  │
+│  │  - ... (13 tools total)                              │  │
+│  └──────────────────────────────────────────────────────┘  │
+│         │                                                   │
+│         ▼                                                   │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │  Firebase Admin SDK                                  │  │
+│  │  (Direct Firestore access with service account)     │  │
+│  └──────────────────────────────────────────────────────┘  │
+│         │                                                   │
+└─────────┼───────────────────────────────────────────────────┘
+          │
+          ▼
+    ┌─────────────┐
+    │  Firestore  │
+    │  (Tasks DB) │
+    └─────────────┘
+```
+
+### Key Architectural Decisions
+
+1. **Separate MCP Server Project**: `task-mcp` is a standalone Node.js project
+2. **MCP Protocol**: Agent connects to MCP server via stdio or SSE transport
+3. **Direct Database Access**: MCP server uses Firebase Admin SDK with service account
+4. **Tool-Based Operations**: All agent task operations go through MCP tools
+5. **API for UI**: Web UI uses REST API for user-initiated operations
+6. **WebSocket for Updates**: Real-time progress updates stream via WebSocket
+
+### Why MCP Server-First?
+
+**Pros**:
+- ✅ **Modularity**: Task tools are completely separate from agentbase.me
+- ✅ **Reusability**: Other platforms can use the same MCP server
+- ✅ **Independent Updates**: Update task tools without deploying agentbase.me
+- ✅ **Standard Protocol**: Follows MCP architecture patterns
+- ✅ **Scalability**: MCP server can scale independently
+- ✅ **Testing**: Easier to test tools in isolation
+- ✅ **Multi-tenant**: MCP server handles per-user authentication
+
+**Cons**:
+- ❌ **Network Latency**: Tool calls go over network (mitigated by local deployment)
+- ❌ **Additional Infrastructure**: Need to deploy and manage MCP server
+- ❌ **Authentication Complexity**: Need to pass user credentials to MCP server
+
+**Decision**: The benefits of modularity and reusability outweigh the complexity.
+
+---
+
+## MCP Server Project Structure
+
+Following the [MCP Server Bootstrap Pattern](https://github.com/prmichaelsen/remember-mcp/blob/main/agent/patterns/bootstrap.md):
+
+```
+task-mcp/
+├── src/
+│   ├── index.ts                      # CLI entry point (stdio)
+│   ├── server.ts                     # Standalone server
+│   ├── server-factory.ts             # Factory for multi-tenant
+│   ├── client.ts                     # Firebase Admin SDK wrapper
+│   ├── types.ts                      # Shared types
+│   │
+│   ├── tools/                        # Task management tools
+│   │   ├── index.ts                  # Tool exports
+│   │   ├── task-get-status.ts
+│   │   ├── task-update-progress.ts
+│   │   ├── task-pause.ts
+│   │   ├── task-resume.ts
+│   │   ├── task-create-milestone.ts
+│   │   ├── task-create-task.ts
+│   │   ├── task-complete-task.ts
+│   │   ├── task-complete-milestone.ts
+│   │   ├── task-init.ts
+│   │   ├── task-get-detailed-status.ts
+│   │   ├── task-sync.ts
+│   │   ├── task-generate-report.ts
+│   │   └── task-validate.ts
+│   │
+│   └── utils/
+│       ├── logger.ts                 # Stdio-safe logging
+│       └── error-serializer.ts       # Error handling
+│
+├── agent/                            # ACP documentation
+│   ├── design/
+│   ├── milestones/
+│   ├── tasks/
+│   └── progress.yaml
+│
+├── package.json
+├── tsconfig.json
+├── esbuild.build.js
+├── firestore-service-account.json    # Service account key (gitignored)
+└── README.md
+```
+
+### Tool Structure (per Bootstrap Pattern)
+
+```typescript
+// src/tools/task-get-status.ts
+import { FirebaseClient } from '../client.js'
+
+export const taskGetStatusTool = {
+  name: 'task_get_status',
+  description: 'Get current task status and progress',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      task_id: {
+        type: 'string',
+        description: 'Task ID to get status for'
+      }
+    },
+    required: ['task_id']
+  }
+}
+
+export async function handleTaskGetStatus(
+  client: FirebaseClient,
+  args: { task_id: string }
+): Promise<string> {
+  try {
+    const task = await client.getTask(args.task_id)
+    if (!task) {
+      throw new Error(`Task not found: ${args.task_id}`)
+    }
+    
+    return JSON.stringify({
+      task_title: task.title,
+      status: task.status,
+      current_milestone: task.progress.current_milestone,
+      overall_progress: task.progress.overall_percentage
+    }, null, 2)
+  } catch (error) {
+    throw new Error(`Failed to get status: ${error instanceof Error ? error.message : String(error)}`)
+  }
+}
+```
+
+---
+
+## agentbase.me Changes
+
+### What Stays in agentbase.me
+
+1. **REST API Routes** (for UI operations)
+   - Uses FirebaseClient from task-mcp (shared business logic)
+   - See [REST API Integration Design](rest-api-integration.md) for full endpoint list
+   - Example endpoints:
+     * `POST /api/tasks` - Create task (from UI)
+     * `GET /api/tasks` - List tasks (for UI)
+     * `GET /api/tasks/:id` - Get task details (for UI)
+     * `DELETE /api/tasks/:id` - Delete task (from UI)
+     * `GET /api/tasks/:id/messages` - Get task messages (for UI)
+
+2. **UI Components**
+   - Task list view
+   - Task detail view
+   - Task thread view
+   - Progress visualization
+
+3. **WebSocket Handler**
+   - Stream progress updates to UI
+   - Handle real-time task status changes
+
+4. **MCP Client Integration**
+   - Connect agent to task-mcp server
+   - Pass user credentials to MCP server
+   - Handle MCP tool calls from agent
+
+### What Lives in task-mcp
+
+1. **Shared Business Logic** (used by both MCP tools and REST API)
+   - FirebaseClient wrapper
+   - TaskDatabaseService
+   - Zod schemas and validation
+
+2. **MCP Tools** (8 core tools for agents)
+   - task_get_status, task_get_next_step, task_update_progress
+   - task_complete_task_item, task_create_milestone, task_create_task_item
+   - task_report_completion, task_add_message
+
+3. **MCP Server Implementation**
+   - Server factory for multi-tenant
+   - Stdio transport
+   - Tool registration and handling
+
+4. **REST API Support** (optional)
+   - FirebaseClient can be imported by agentbase.me
+   - Enables dual interface (MCP + REST)
+   - See [REST API Integration Design](rest-api-integration.md)
+
+---
+
+## Data Model
+
+### Task Document (Firestore)
+
+```typescript
+interface Task {
+  id: string
+  user_id: string
+  title: string
+  description: string
+  status: 'not_started' | 'in_progress' | 'paused' | 'completed' | 'failed'
+  created_at: string
+  updated_at: string
+  started_at?: string
+  completed_at?: string
+  
+  // ACP Structure
+  progress: {
+    current_milestone: string
+    current_task: string
+    overall_percentage: number
+    milestones: Milestone[]
+    tasks: Record<string, TaskItem[]>
+  }
+  
+  // Execution State
+  execution: {
+    api_messages: ApiMessage[]
+    task_messages: TaskMessage[]
+    tool_results: ToolResult[]
+    error?: string
+    abort_reason?: string
+  }
+  
+  // Configuration
+  config: {
+    model: string
+    system_prompt: string
+    auto_approve: boolean
+    max_iterations?: number
+    timeout_minutes?: number
+  }
+  
+  metadata?: {
+    conversation_id?: string
+    parent_task_id?: string
+    tags?: string[]
+  }
+}
+```
+
+---
+
+## Implementation Phases
+
+### Phase 1: MCP Server Foundation (Week 1-2)
+
+**Deliverables**:
+- [ ] Create task-mcp project structure
+- [ ] Implement Firebase Admin SDK client
+- [ ] Create 8 core task management tools
+- [ ] Implement MCP server with stdio transport
+- [ ] Write unit tests for tools
+- [ ] Deploy MCP server
+
+**Success Criteria**:
+- MCP server starts successfully
+- Tools can be called via MCP protocol
+- Firebase operations work correctly
+- Tests pass
+
+### Phase 2: agentbase.me Integration (Week 3-4)
+
+**Deliverables**:
+- [ ] Task data model in agentbase.me
+- [ ] API routes for UI operations
+- [ ] MCP client integration in agent
+- [ ] Task conversation type
+- [ ] Basic UI components
+- [ ] WebSocket progress updates
+
+**Success Criteria**:
+- Can create task from UI
+- Agent can connect to MCP server
+- Agent can call task tools
+- UI displays task progress
+- Real-time updates work
+
+### Phase 3: ACP Workflow Tools (Week 5-6)
+
+**Deliverables**:
+- [ ] 5 ACP workflow tools in task-mcp
+- [ ] task_init - Initialize context
+- [ ] task_get_detailed_status - Detailed status
+- [ ] task_sync - Sync documentation
+- [ ] task_generate_report - Generate report
+- [ ] task_validate - Validate structure
+
+**Success Criteria**:
+- All 13 tools implemented
+- Agent can use workflow tools
+- Reports generate correctly
+- Validation works
+
+### Phase 4: Autonomous Execution (Week 7-8)
+
+**Deliverables**:
+- [ ] Pessimistic execution loop
+- [ ] Message queue system
+- [ ] Auto-approval system
+- [ ] Safety limits
+- [ ] Error recovery
+- [ ] UI polish
+
+**Success Criteria**:
+- Agent works through all milestones
+- Safety limits prevent runaway execution
+- Errors handled gracefully
+- UI is polished and intuitive
+
+---
+
+## MCP Server Authentication
+
+### Multi-Tenant Authentication
+
+The MCP server needs to know which user is making requests. Options:
+
+**Option A: JWT in Tool Arguments**
+```typescript
+// Every tool call includes user_id
+{
+  "tool": "task_get_status",
+  "arguments": {
+    "user_id": "user_abc123",  // Passed by agent
+    "task_id": "task_xyz789"
+  }
+}
+```
+
+**Option B: MCP Server Factory (Recommended)**
+```typescript
+// Agent creates per-user MCP server instance
+const mcpServer = createTaskMCPServer(userId, firebaseToken)
+```
+
+**Decision**: Use Option B (server factory) for better security and isolation.
+
+---
+
+## Deployment
+
+### task-mcp Deployment Options
+
+**Option 1: Cloud Run (Recommended)**
+- Deploy as Cloud Run service
+- Use SSE transport for HTTP connections
+- Auto-scaling based on load
+- Easy to update independently
+
+**Option 2: Cloud Functions**
+- Deploy as Cloud Function
+- Triggered by agent requests
+- Serverless, pay-per-use
+- Cold start latency
+
+**Option 3: Compute Engine**
+- Deploy on VM
+- Always-on, low latency
+- More control, more cost
+- Good for high-volume usage
+
+**Recommendation**: Start with Cloud Run for balance of cost, performance, and ease of deployment.
+
+---
+
+## Security Considerations
+
+### MCP Server Security
+
+**Requirements**:
+- MCP server validates user identity
+- Tools enforce user-scoped data access
+- Service account has minimal permissions
+- Audit logging for all operations
+
+**Implementation**:
+- Use Firebase Admin SDK with service account
+- Validate user_id in every tool call
+- Firestore security rules as backup
+- Log all tool executions
+
+### API Security
+
+**Requirements**:
+- API routes require authentication
+- Users can only access their own tasks
+- Rate limiting per user
+- Input validation
+
+**Implementation**:
+- Firebase Auth tokens
+- User ID from auth token
+- Firestore security rules
+- Zod schema validation
+
+---
+
+## Success Metrics
+
+### Functional Metrics
+
+- [ ] MCP server deploys successfully
+- [ ] Agent can connect to MCP server
+- [ ] All 13 tools work correctly
+- [ ] Tasks execute autonomously
+- [ ] Progress tracked accurately
+- [ ] UI displays real-time updates
+
+### Performance Metrics
+
+- [ ] Tool call latency < 200ms
+- [ ] MCP server uptime > 99.9%
+- [ ] Task creation < 1 second
+- [ ] Progress updates < 500ms latency
+
+### User Experience Metrics
+
+- [ ] Intuitive task creation
+- [ ] Clear progress indicators
+- [ ] Responsive UI
+- [ ] Graceful error handling
+
+---
+
+## References
+
+- [Roo Code Repository](https://github.com/RooVetGit/Roo-Code)
+- [Agent Context Protocol (ACP)](../../../AGENT.md)
+- [MCP Server Bootstrap Pattern](https://github.com/prmichaelsen/remember-mcp/blob/main/agent/patterns/bootstrap.md)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Firebase Admin SDK](https://firebase.google.com/docs/admin/setup)
+- [REST API Integration Design](rest-api-integration.md) - Dual interface architecture
+- [MCP Best Practices](https://www.philschmid.de/mcp-best-practices) - Industry best practices
+
+---
+
+**Status**: Design Specification
+**Architecture**: MCP Server-First
+**Next Action**: Begin Phase 1 - Create task-mcp project
+**Owner**: Development Team
+**Created**: 2026-02-16
+**Last Updated**: 2026-02-16