@prmichaelsen/task-mcp 0.2.0

package/agent/design/api-dto-design.md

@@ -0,0 +1,394 @@
+# API DTO Design
+
+**Concept**: Define Data Transfer Objects (DTOs) for REST API responses
+**Created**: 2026-02-16
+**Status**: Design Specification
+
+---
+
+## Overview
+
+This document defines the API response DTOs for task-mcp REST API. These DTOs are based on the internal schemas but exclude internal fields and match the structure expected by agentbase.me.
+
+## Problem Statement
+
+Our internal schemas ([`src/schemas/task.ts`](../../src/schemas/task.ts)) contain fields that should not be exposed via REST API:
+
+- `execution.api_messages` - Internal Anthropic API conversation
+- `execution.tool_results` - Internal MCP tool execution details
+- Other internal implementation details
+
+We need separate DTOs for API responses that:
+1. Exclude internal fields
+2. Match agentbase.me's expected structure
+3. Use updated field naming conventions
+4. Provide clear TypeScript types for API consumers
+
+## Solution
+
+Create API response DTOs in `src/dto/task-api.dto.ts` that transform internal schemas into public API responses.
+
+### DTO Structure
+
+```typescript
+// src/dto/task-api.dto.ts
+
+/**
+ * API Response DTOs
+ * 
+ * These DTOs define the structure of REST API responses.
+ * They exclude internal fields and match agentbase.me expectations.
+ */
+
+// ============================================================================
+// Status Enums
+// ============================================================================
+
+export type TaskStatus = 'not_started' | 'in_progress' | 'paused' | 'completed' | 'failed'
+export type MilestoneStatus = 'not_started' | 'in_progress' | 'completed'
+export type TaskItemStatus = 'not_started' | 'in_progress' | 'completed'
+export type MessageRole = 'user' | 'assistant' | 'system'
+
+// ============================================================================
+// Nested DTOs
+// ============================================================================
+
+export interface TaskItemApiResponse {
+  id: string
+  name: string
+  description: string
+  status: TaskItemStatus
+  estimated_hours?: number
+  completed_at?: string  // ISO 8601 timestamp
+  notes?: string
+}
+
+export interface MilestoneApiResponse {
+  id: string
+  name: string
+  description: string
+  status: MilestoneStatus
+  progress: number  // 0-100
+  tasks_completed: number
+  tasks_total: number
+  started_at?: string  // ISO 8601 timestamp
+  completed_at?: string  // ISO 8601 timestamp
+}
+
+export interface TaskProgressApiResponse {
+  current_milestone: string
+  current_task: string
+  overall_percentage: number  // 0-100
+  milestones: MilestoneApiResponse[]
+  tasks: Record<string, TaskItemApiResponse[]>  // Keyed by milestone ID
+}
+
+export interface TaskConfigApiResponse {
+  system_prompt: string
+  auto_approve: boolean
+  max_iterations?: number
+}
+
+export interface TaskMetadataApiResponse {
+  conversation_id?: string
+  parent_task_id?: string
+  tags?: string[]
+}
+
+// ============================================================================
+// Main Task DTO
+// ============================================================================
+
+export interface TaskApiResponse {
+  id: string
+  user_id: string
+  title: string
+  description: string
+  status: TaskStatus
+  created_at: string  // ISO 8601 timestamp
+  updated_at: string  // ISO 8601 timestamp
+  started_at?: string  // ISO 8601 timestamp
+  completed_at?: string  // ISO 8601 timestamp
+  
+  progress: TaskProgressApiResponse
+  config: TaskConfigApiResponse
+  metadata?: TaskMetadataApiResponse
+  
+  // Note: execution field is EXCLUDED from API responses
+  // Internal fields (api_messages, tool_results) are not exposed
+}
+
+// ============================================================================
+// List Response DTO
+// ============================================================================
+
+export interface TaskListApiResponse {
+  tasks: TaskApiResponse[]
+  total: number
+}
+
+// ============================================================================
+// Message DTO
+// ============================================================================
+
+export interface TaskMessageApiResponse {
+  id: string
+  task_id: string
+  role: MessageRole
+  content: string
+  timestamp: string  // ISO 8601 timestamp
+  metadata?: any
+}
+
+export interface TaskMessageListApiResponse {
+  messages: TaskMessageApiResponse[]
+  total: number
+}
+```
+
+## Transformation Logic
+
+### From Schema to DTO
+
+```typescript
+// src/dto/transformers.ts
+
+import { Task, TaskMessage } from '../schemas/task.js'
+import { TaskApiResponse, TaskMessageApiResponse } from './task-api.dto.js'
+
+/**
+ * Transform internal Task schema to API response DTO
+ * Excludes internal execution details
+ */
+export function toTaskApiResponse(task: Task): TaskApiResponse {
+  return {
+    id: task.id,
+    user_id: task.user_id,
+    title: task.title,
+    description: task.description,
+    status: task.status,
+    created_at: task.created_at,
+    updated_at: task.updated_at,
+    started_at: task.started_at,
+    completed_at: task.completed_at,
+    
+    progress: {
+      current_milestone: task.progress.current_milestone,
+      current_task: task.progress.current_task,
+      overall_percentage: task.progress.overall_percentage,
+      milestones: task.progress.milestones.map(m => ({
+        id: m.id,
+        name: m.name,
+        description: m.description,
+        status: m.status,
+        progress: m.progress,
+        tasks_completed: m.tasks_completed,
+        tasks_total: m.tasks_total,
+        started_at: m.started_at,
+        completed_at: m.completed_at
+      })),
+      tasks: task.progress.tasks
+    },
+    
+    config: {
+      system_prompt: task.config.system_prompt,
+      auto_approve: task.config.auto_approve,
+      max_iterations: task.config.max_iterations
+    },
+    
+    metadata: task.metadata
+    
+    // execution field is intentionally excluded
+  }
+}
+
+/**
+ * Transform internal TaskMessage schema to API response DTO
+ */
+export function toTaskMessageApiResponse(message: TaskMessage): TaskMessageApiResponse {
+  return {
+    id: message.id,
+    task_id: message.task_id,
+    role: message.role,
+    content: message.content,
+    timestamp: message.timestamp,
+    metadata: message.metadata
+  }
+}
+```
+
+## Field Mapping
+
+### Included Fields
+
+| Schema Field | DTO Field | Notes |
+|--------------|-----------|-------|
+| `id` | `id` | ✅ Included |
+| `user_id` | `user_id` | ✅ Included |
+| `title` | `title` | ✅ Included |
+| `description` | `description` | ✅ Included |
+| `status` | `status` | ✅ Included |
+| `created_at` | `created_at` | ✅ Included |
+| `updated_at` | `updated_at` | ✅ Included |
+| `started_at` | `started_at` | ✅ Included |
+| `completed_at` | `completed_at` | ✅ Included |
+| `progress` | `progress` | ✅ Included (all subfields) |
+| `config` | `config` | ✅ Included (all subfields) |
+| `metadata` | `metadata` | ✅ Included (all subfields) |
+
+### Excluded Fields
+
+| Schema Field | Reason for Exclusion |
+|--------------|---------------------|
+| `execution.api_messages` | Internal Anthropic API conversation |
+| `execution.task_messages` | Stored in separate messages collection |
+| `execution.tool_results` | Internal MCP tool execution details |
+| `execution.error` | Internal error details (may expose sensitive info) |
+| `execution.abort_reason` | Internal abort details |
+
+## Usage in REST API
+
+### Example: GET /api/tasks/:taskId
+
+```typescript
+// REST API handler
+import { TaskDatabaseService } from '../services/task-database.service.js'
+import { toTaskApiResponse } from '../dto/transformers.js'
+
+export async function getTask(req, res) {
+  const { taskId } = req.params
+  const userId = req.user.id  // From auth middleware
+  
+  const task = await TaskDatabaseService.getTask(userId, taskId)
+  
+  if (!task) {
+    return res.status(404).json({ error: 'Task not found' })
+  }
+  
+  // Transform to DTO before sending
+  const dto = toTaskApiResponse(task)
+  
+  return res.json(dto)
+}
+```
+
+### Example: GET /api/tasks
+
+```typescript
+export async function listTasks(req, res) {
+  const userId = req.user.id
+  const { status, limit = 10, offset = 0 } = req.query
+  
+  const tasks = await TaskDatabaseService.listTasks(userId, limit)
+  
+  // Transform all tasks to DTOs
+  const dtos = tasks.map(toTaskApiResponse)
+  
+  return res.json({
+    tasks: dtos,
+    total: dtos.length
+  })
+}
+```
+
+## Compatibility with agentbase.me
+
+The DTOs match the structure expected by agentbase.me's mock service:
+
+**Reference**: [`/home/prmichaelsen/agentbase.me/src/services/task-mock.service.ts`](../../../agentbase.me/src/services/task-mock.service.ts)
+
+### Key Differences from Mock Service
+
+1. ✅ **Updated field names**: `completed_at` (not `completed_date`)
+2. ✅ **Simplified config**: No `model` or `timeout_minutes` fields
+3. ✅ **Excluded execution**: Internal fields not exposed
+
+### Migration Path for agentbase.me
+
+When agentbase.me switches from mock service to real task-mcp client:
+
+```typescript
+// Before (mock service)
+import { TaskMockService } from './services/task-mock.service'
+const tasks = await TaskMockService.getTasks()
+
+// After (real client)
+import { TaskMCPClient } from 'task-mcp/client'
+const client = new TaskMCPClient({ apiUrl: 'https://task-mcp.example.com' })
+const tasks = await client.getTasks()
+
+// Response structure is identical!
+```
+
+## Benefits
+
+1. **Security**: Internal implementation details not exposed
+2. **Stability**: API contract separate from internal schema changes
+3. **Clarity**: Clear TypeScript types for API consumers
+4. **Compatibility**: Matches agentbase.me expectations
+5. **Flexibility**: Can evolve internal schemas without breaking API
+
+## Implementation Files
+
+When implementing, create:
+
+1. `src/dto/task-api.dto.ts` - DTO type definitions
+2. `src/dto/transformers.ts` - Schema-to-DTO transformation functions
+3. `src/dto/index.ts` - Export all DTOs
+
+Update `package.json` exports:
+```json
+{
+  "exports": {
+    "./dto": {
+      "types": "./dist/dto/index.d.ts",
+      "import": "./dist/dto/index.js"
+    }
+  }
+}
+```
+
+## Future Considerations
+
+### Input DTOs (for write operations)
+
+When implementing write operations, create input DTOs:
+
+```typescript
+export interface CreateTaskDto {
+  title: string
+  description: string
+  config?: Partial<TaskConfigApiResponse>
+  metadata?: TaskMetadataApiResponse
+}
+
+export interface UpdateTaskDto {
+  title?: string
+  description?: string
+  status?: TaskStatus
+  config?: Partial<TaskConfigApiResponse>
+}
+```
+
+### Validation
+
+Use Zod to validate DTOs:
+
+```typescript
+import { z } from 'zod'
+
+export const CreateTaskDtoSchema = z.object({
+  title: z.string().min(1).max(200),
+  description: z.string().min(1).max(2000),
+  config: z.object({
+    system_prompt: z.string().optional(),
+    auto_approve: z.boolean().optional(),
+    max_iterations: z.number().min(1).max(1000).optional()
+  }).optional()
+})
+```
+
+---
+
+**Status**: Design Complete
+**Recommendation**: Implement DTOs when building REST API (Task 90)