@prmichaelsen/task-mcp 0.2.0

package/agent/tasks/task-87-task-database-service.md

@@ -0,0 +1,220 @@
+# Task 87: Task Database Service
+
+**Milestone**: Milestone 1 - Task Infrastructure
+**Estimated Time**: 12 hours
+**Dependencies**: Task 86 (Task Data Model and Schemas)
+**Status**: Not Started
+
+---
+
+## Objective
+
+Create a database service for task CRUD operations, task message operations, and progress tracking. This service will handle all Firestore interactions for tasks.
+
+## Steps
+
+### 1. Create TaskDatabaseService Class
+
+Create `src/services/task-database.service.ts` with methods for:
+- Creating tasks
+- Reading tasks
+- Updating tasks
+- Deleting tasks
+- Listing user tasks
+
+### 2. Implement Task Message Operations
+
+Add methods for:
+- Adding messages to task
+- Getting task messages
+- Updating message
+- Deleting message
+
+### 3. Implement Progress Operations
+
+Add methods for:
+- Updating overall progress
+- Creating milestone
+- Updating milestone
+- Completing milestone
+- Creating task item
+- Updating task item
+- Completing task item
+
+### 4. Add Query Methods
+
+Add methods for:
+- Get tasks by status
+- Get active tasks
+- Get completed tasks
+- Search tasks by title
+
+### 5. Write Unit Tests
+
+Create `src/services/__tests__/task-database.service.spec.ts`:
+- Test CRUD operations with mocked Firestore
+- Test progress operations
+- Test query methods
+- Test error handling
+
+### 6. Write E2E Tests
+
+Create `src/services/__tests__/task-database.service.e2e.ts`:
+- Test with real Firestore emulator
+- Test concurrent operations
+- Test transaction handling
+
+## Verification
+
+- [ ] All CRUD operations work
+- [ ] Task messages can be added/retrieved
+- [ ] Progress can be updated
+- [ ] Milestones can be managed
+- [ ] Task items can be managed
+- [ ] Query methods return correct results
+- [ ] User isolation is enforced
+- [ ] Unit tests pass
+- [ ] E2E tests pass
+- [ ] Error handling works correctly
+
+## Example Service Structure
+
+```typescript
+// src/services/task-database.service.ts
+import { getDocument, setDocument, addDocument, queryDocuments } from '@prmichaelsen/firebase-admin-sdk-v8'
+import { getUserTasks, getUserTaskMessages } from '@/constant/collections'
+import { TaskSchema, type Task, type Milestone, type TaskItem } from '@/schemas/task'
+
+export class TaskDatabaseService {
+  /**
+   * Create a new task
+   */
+  static async createTask(
+    userId: string,
+    title: string,
+    description: string,
+    config?: Partial<Task['config']>
+  ): Promise<Task> {
+    const now = new Date().toISOString()
+    
+    const task: Omit<Task, 'id'> = {
+      user_id: userId,
+      title,
+      description,
+      status: 'not_started',
+      created_at: now,
+      updated_at: now,
+      progress: {
+        current_milestone: '',
+        current_task: '',
+        overall_percentage: 0,
+        milestones: [],
+        tasks: {}
+      },
+      execution: {
+        api_messages: [],
+        task_messages: [],
+        tool_results: []
+      },
+      config: {
+        model: config?.model || 'us.anthropic.claude-sonnet-4-5-20250929-v1:0',
+        system_prompt: config?.system_prompt || '',
+        auto_approve: config?.auto_approve ?? true,
+        max_iterations: config?.max_iterations || 100,
+        timeout_minutes: config?.timeout_minutes || 120
+      }
+    }
+    
+    const tasksPath = getUserTasks(userId)
+    const docRef = await addDocument(tasksPath, task)
+    
+    return {
+      id: docRef.id,
+      ...task
+    }
+  }
+  
+  /**
+   * Get a task by ID
+   */
+  static async getTask(userId: string, taskId: string): Promise<Task | null> {
+    const tasksPath = getUserTasks(userId)
+    const doc = await getDocument(tasksPath, taskId)
+    
+    if (!doc) return null
+    
+    const result = TaskSchema.safeParse({ id: taskId, ...doc })
+    return result.success ? result.data : null
+  }
+  
+  /**
+   * Update task status
+   */
+  static async updateTaskStatus(
+    userId: string,
+    taskId: string,
+    status: Task['status']
+  ): Promise<void> {
+    const tasksPath = getUserTasks(userId)
+    await setDocument(tasksPath, taskId, {
+      status,
+      updated_at: new Date().toISOString()
+    }, { merge: true })
+  }
+  
+  /**
+   * Create a milestone
+   */
+  static async createMilestone(
+    userId: string,
+    taskId: string,
+    milestone: Milestone
+  ): Promise<void> {
+    const task = await this.getTask(userId, taskId)
+    if (!task) throw new Error('Task not found')
+    
+    task.progress.milestones.push(milestone)
+    
+    const tasksPath = getUserTasks(userId)
+    await setDocument(tasksPath, taskId, {
+      progress: task.progress,
+      updated_at: new Date().toISOString()
+    }, { merge: true })
+  }
+  
+  /**
+   * Add message to task
+   */
+  static async addMessage(
+    userId: string,
+    taskId: string,
+    role: 'user' | 'assistant' | 'system',
+    content: string,
+    metadata?: any
+  ): Promise<string> {
+    const messagesPath = getUserTaskMessages(userId, taskId)
+    const message = {
+      task_id: taskId,
+      role,
+      content,
+      timestamp: new Date().toISOString(),
+      metadata
+    }
+    
+    const docRef = await addDocument(messagesPath, message)
+    return docRef.id
+  }
+  
+  // ... more methods
+}
+```
+
+## Files to Create
+
+- `src/services/task-database.service.ts`
+- `src/services/__tests__/task-database.service.spec.ts`
+- `src/services/__tests__/task-database.service.e2e.ts`
+
+---
+
+**Next Task**: [Task 88: Task Execution Engine](task-88-task-execution-engine.md)

package/agent/tasks/task-88-firebase-client-wrapper.md

@@ -0,0 +1,139 @@
+# Task 88: Firebase Client Wrapper & MCP Tools Foundation
+
+**Milestone**: Milestone 2 - MCP Server Foundation
+**Estimated Time**: 16 hours (revised from original scope)
+**Dependencies**: Task 87 (Task Database Service)
+**Status**: Not Started
+**Last Updated**: 2026-02-16
+
+---
+
+## Objective
+
+**REVISED**: Create Firebase Admin SDK client wrapper and foundational MCP tools for task-mcp server. This task was originally scoped for agentbase.me TaskExecutor but has been revised to match task-mcp's role as an MCP tool server that provides instructions to tenant platforms.
+
+**Original Scope** (archived): TaskExecutor with Bedrock integration for agentbase.me
+**Revised Scope**: Firebase client + core MCP tools for task-mcp server
+
+---
+
+## Steps
+
+### 1. Create Firebase Client Wrapper
+
+Create `src/client.ts`:
+- Wrapper around TaskDatabaseService
+- Service account authentication
+- User-scoped operations
+- Connection management
+- Error handling
+
+### 2. Create Core MCP Tool: task_get_status
+
+Create `src/tools/task-get-status.ts`:
+- Get current task status and progress
+- Return milestone and task information
+- Show overall progress percentage
+
+### 3. Create Core MCP Tool: task_get_next_step
+
+Create `src/tools/task-get-next-step.ts`:
+- Find current task item from progress
+- Return instructions for what to do next
+- Include steps and verification criteria
+
+### 4. Create Core MCP Tool: task_update_progress
+
+Create `src/tools/task-update-progress.ts`:
+- Update overall progress percentage
+- Update milestone progress
+- Recalculate completion metrics
+
+### 5. Create Core MCP Tool: task_complete_task_item
+
+Create `src/tools/task-complete-task-item.ts`:
+- Mark a task item as complete
+- Update milestone progress
+- Move to next task if available
+
+### 6. Create Core MCP Tool: task_create_milestone
+
+Create `src/tools/task-create-milestone.ts`:
+- Add a new milestone to task
+- Initialize milestone with tasks
+- Update progress tracking
+
+### 7. Create Core MCP Tool: task_create_task_item
+
+Create `src/tools/task-create-task-item.ts`:
+- Add a task item to a milestone
+- Update milestone task count
+- Return confirmation
+
+### 8. Create Core MCP Tool: task_report_completion
+
+Create `src/tools/task-report-completion.ts`:
+- Agent reports task item completion
+- Update progress
+- Get next instructions
+
+### 9. Create Core MCP Tool: task_add_message
+
+Create `src/tools/task-add-message.ts`:
+- Add message to task thread
+- Support user, assistant, system roles
+- Return message ID
+
+### 10. Create Tools Index
+
+Create `src/tools/index.ts`:
+- Export all tool definitions
+- Export all tool handlers
+- Create tool registry
+
+### 11. Write Unit Tests
+
+Create colocated test for each tool:
+- Test tool definitions
+- Test handlers with mocked client
+- Test error handling
+- Verify JSON responses
+
+## Verification
+
+- [ ] FirebaseClient wrapper created
+- [ ] All 8 core tools implemented
+- [ ] Each tool has definition and handler
+- [ ] Tools return JSON strings
+- [ ] Error handling works correctly
+- [ ] Unit tests pass for all tools
+- [ ] Tools follow MCP Bootstrap Pattern
+- [ ] TypeScript compiles without errors
+
+## Notes on Revision
+
+**Why Revised**: Original task described TaskExecutor for agentbase.me with Bedrock integration. However, task-mcp is an MCP server that exposes tools, not an execution engine. The execution happens in the tenant platform (agentbase.me).
+
+**Architecture Clarification**: 
+- task-mcp provides **instructions** via MCP tools
+- Tenant platform's agent **executes** those instructions
+- Agent reports back to task-mcp via tools
+- task-mcp tracks progress in Firestore
+
+## Files to Create
+
+- `src/client.ts` + `.spec.ts`
+- `src/tools/task-get-status.ts` + `.spec.ts`
+- `src/tools/task-get-next-step.ts` + `.spec.ts`
+- `src/tools/task-update-progress.ts` + `.spec.ts`
+- `src/tools/task-complete-task-item.ts` + `.spec.ts`
+- `src/tools/task-create-milestone.ts` + `.spec.ts`
+- `src/tools/task-create-task-item.ts` + `.spec.ts`
+- `src/tools/task-report-completion.ts` + `.spec.ts`
+- `src/tools/task-add-message.ts` + `.spec.ts`
+- `src/tools/index.ts`
+- `.env.example`
+
+---
+
+**Next Task**: [Task 89: MCP Server Implementation](task-89-mcp-server-implementation.md)

package/agent/tasks/task-88-task-execution-engine.md

@@ -0,0 +1,277 @@
+# Task 88: Task Execution Engine
+
+**Milestone**: Milestone 1 - Task Infrastructure
+**Estimated Time**: 16 hours
+**Dependencies**: Task 87 (Task Database Service)
+**Status**: Not Started
+
+---
+
+## Objective
+
+Create a simplified task execution engine adapted from Roo Code's Task class. This engine manages task lifecycle (start, pause, resume, stop), streams API responses, coordinates tool execution, and persists state to Firestore.
+
+## Steps
+
+### 1. Create TaskExecutor Class
+
+Create `src/lib/task-execution/TaskExecutor.ts`:
+- Initialize with task ID and user ID
+- Load task state from Firestore
+- Manage execution lifecycle
+- Stream API responses from Bedrock
+- Coordinate tool execution
+- Emit events for UI updates
+
+### 2. Create TaskLifecycle Manager
+
+Create `src/lib/task-execution/TaskLifecycle.ts`:
+- Handle start/pause/resume/stop transitions
+- Validate state transitions
+- Update task status in Firestore
+- Emit lifecycle events
+
+### 3. Create TaskPersistence Layer
+
+Create `src/lib/task-execution/TaskPersistence.ts`:
+- Save API messages to Firestore
+- Save task messages to Firestore
+- Save tool results to Firestore
+- Load execution state from Firestore
+- Implement checkpoint/resume logic
+
+### 4. Integrate with Bedrock Chat
+
+Adapt existing Bedrock chat integration:
+- Use `streamChatResponse` from `src/lib/chat/bedrock.ts`
+- Pass task-specific tools
+- Handle tool execution results
+- Stream responses to task thread
+
+### 5. Implement Event System
+
+Create event emitter for:
+- `task:started`
+- `task:paused`
+- `task:resumed`
+- `task:stopped`
+- `task:completed`
+- `task:error`
+- `task:progress_update`
+- `task:message`
+
+### 6. Write Tests
+
+Create tests for:
+- Task lifecycle transitions
+- API streaming
+- Tool execution
+- State persistence
+- Error handling
+- Event emission
+
+## Verification
+
+- [ ] Can start task execution
+- [ ] Can pause task execution
+- [ ] Can resume task execution
+- [ ] Can stop task execution
+- [ ] API responses stream correctly
+- [ ] Tools execute correctly
+- [ ] State persists to Firestore
+- [ ] Events emit correctly
+- [ ] Errors handled gracefully
+- [ ] Tests pass
+
+## Example TaskExecutor Structure
+
+```typescript
+// src/lib/task-execution/TaskExecutor.ts
+import { EventEmitter } from 'events'
+import { TaskDatabaseService } from '@/services/task-database.service'
+import { streamChatResponse } from '@/lib/chat/bedrock'
+import { createBedrockClient } from '@/lib/chat/bedrock'
+import type { Task } from '@/schemas/task'
+
+export class TaskExecutor extends EventEmitter {
+  private taskId: string
+  private userId: string
+  private task: Task | null = null
+  private isRunning = false
+  private isPaused = false
+  private abortController: AbortController | null = null
+  
+  constructor(taskId: string, userId: string) {
+    super()
+    this.taskId = taskId
+    this.userId = userId
+  }
+  
+  /**
+   * Start task execution
+   */
+  async start(): Promise<void> {
+    // Load task from Firestore
+    this.task = await TaskDatabaseService.getTask(this.userId, this.taskId)
+    if (!this.task) {
+      throw new Error('Task not found')
+    }
+    
+    // Update status
+    await TaskDatabaseService.updateTaskStatus(this.userId, this.taskId, 'in_progress')
+    this.task.status = 'in_progress'
+    
+    // Emit event
+    this.emit('task:started', { taskId: this.taskId })
+    
+    // Start execution loop
+    this.isRunning = true
+    await this.executionLoop()
+  }
+  
+  /**
+   * Pause task execution
+   */
+  async pause(): Promise<void> {
+    this.isPaused = true
+    this.abortController?.abort()
+    
+    await TaskDatabaseService.updateTaskStatus(this.userId, this.taskId, 'paused')
+    this.emit('task:paused', { taskId: this.taskId })
+  }
+  
+  /**
+   * Resume task execution
+   */
+  async resume(): Promise<void> {
+    this.isPaused = false
+    await TaskDatabaseService.updateTaskStatus(this.userId, this.taskId, 'in_progress')
+    this.emit('task:resumed', { taskId: this.taskId })
+    
+    await this.executionLoop()
+  }
+  
+  /**
+   * Stop task execution
+   */
+  async stop(): Promise<void> {
+    this.isRunning = false
+    this.abortController?.abort()
+    
+    await TaskDatabaseService.updateTaskStatus(this.userId, this.taskId, 'paused')
+    this.emit('task:stopped', { taskId: this.taskId })
+  }
+  
+  /**
+   * Main execution loop
+   */
+  private async executionLoop(): Promise<void> {
+    while (this.isRunning && !this.isPaused) {
+      try {
+        // Get current milestone and task
+        const currentMilestone = this.getCurrentMilestone()
+        const currentTask = this.getCurrentTask()
+        
+        if (!currentTask) {
+          // All tasks complete
+          await this.complete()
+          break
+        }
+        
+        // Execute task
+        await this.executeTask(currentTask)
+        
+        // Update progress
+        await this.updateProgress()
+        
+      } catch (error) {
+        await this.handleError(error)
+        break
+      }
+    }
+  }
+  
+  /**
+   * Execute a single task
+   */
+  private async executeTask(taskItem: any): Promise<void> {
+    // Create Bedrock client
+    const bedrock = createBedrockClient()
+    
+    // Prepare messages
+    const messages = this.prepareMessages()
+    
+    // Prepare tools
+    const tools = this.prepareTools()
+    
+    // Stream response
+    this.abortController = new AbortController()
+    
+    const result = await streamChatResponse(
+      bedrock,
+      messages,
+      tools,
+      {
+        maxTokens: 4096,
+        temperature: 0.7,
+        systemPrompt: this.task!.config.system_prompt
+      },
+      (chunk) => {
+        // Emit chunk event
+        this.emit('task:message', {
+          taskId: this.taskId,
+          role: 'assistant',
+          content: chunk,
+          streaming: true
+        })
+      },
+      (toolCall) => {
+        // Handle tool call
+        this.emit('task:tool_call', {
+          taskId: this.taskId,
+          toolCall
+        })
+      }
+    )
+    
+    // Save result
+    await this.saveResult(result)
+  }
+  
+  /**
+   * Complete task
+   */
+  private async complete(): Promise<void> {
+    await TaskDatabaseService.updateTaskStatus(this.userId, this.taskId, 'completed')
+    this.isRunning = false
+    this.emit('task:completed', { taskId: this.taskId })
+  }
+  
+  /**
+   * Handle error
+   */
+  private async handleError(error: any): Promise<void> {
+    await TaskDatabaseService.updateTaskStatus(this.userId, this.taskId, 'failed')
+    this.isRunning = false
+    this.emit('task:error', {
+      taskId: this.taskId,
+      error: error instanceof Error ? error.message : String(error)
+    })
+  }
+  
+  // ... more methods
+}
+```
+
+## Files to Create
+
+- `src/lib/task-execution/TaskExecutor.ts`
+- `src/lib/task-execution/TaskLifecycle.ts`
+- `src/lib/task-execution/TaskPersistence.ts`
+- `src/lib/task-execution/__tests__/TaskExecutor.spec.ts`
+- `src/lib/task-execution/__tests__/TaskLifecycle.spec.ts`
+- `src/lib/task-execution/__tests__/TaskPersistence.spec.ts`
+
+---
+
+**Next Task**: [Task 89: Task API Endpoints](task-89-task-api-endpoints.md)