Tasks API

Dispatch long-running tasks to the Agent service for project analysis and knowledge base generation.

Task Types

Type	Description	Duration
analyze-project	Analyze project structure, tech stack, and architecture	~30s - 2min
generate-knowledge-base	Generate embeddings and store in vector database	~1min - 10min

API Endpoints

POST/tasks

Dispatch a new task to the Agent service.

// Request
{
  "type": "generate-knowledge-base",
  "projectId": "project-123",
  "repoUrl": "https://github.com/user/repo",  // Optional
  "branch": "main",  // Optional, default: main
  "config": {  // Optional
    "includeTests": true
  }
}

// Response
{
  "id": "ai_task_abc123",
  "projectId": "project-123",
  "type": "generate-knowledge-base",
  "status": "queued",
  "createdAt": "2024-01-15T10:30:00Z"
}

GET/tasks/:taskId

Get the current status of a task.

// Response
{
  "id": "ai_task_abc123",
  "projectId": "project-123",
  "type": "generate-knowledge-base",
  "status": "completed",  // pending | queued | running | completed | failed
  "result": {
    "chunksGenerated": 47,
    "generatedAt": "2024-01-15T10:32:00Z"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "startedAt": "2024-01-15T10:30:05Z",
  "completedAt": "2024-01-15T10:32:00Z"
}

GET/tasks?projectId=:projectId

List all tasks for a project.

Task Status Flow

pending → queued → running → completed
                          ↘ failed

pending - Task created, not yet dispatched

queued - Dispatched to Agent, waiting to start

running - Agent is actively processing

completed - Task finished successfully

failed - Task encountered an error

React Hook

import { useAITask } from '@/hooks/use-ai-task'

function ProjectSetup({ projectId, repoUrl }) {
  const {
    task,           // TaskStatus | null
    isPolling,      // boolean
    error,          // Error | null
    dispatch,       // (request: TaskRequest) => Promise<TaskStatus>
    analyzeProject, // (projectId, repoUrl?, branch?) => Promise<TaskStatus>
    generateKnowledgeBase, // (projectId, repoUrl?, branch?) => Promise<TaskStatus>
    startPolling,   // (taskId: string) => void
    stopPolling,    // () => void
    refreshStatus,  // () => Promise<TaskStatus | null>
  } = useAITask({
    pollInterval: 3000,  // Default: 3000ms
    autoPoll: true,      // Auto-start polling after dispatch
    onStatusChange: (status) => {
      console.log('Status:', status.status)
    },
    onComplete: (status) => {
      console.log('Done!', status.result)
    },
    onError: (error, status) => {
      console.error('Failed:', error.message)
    },
  })

  return (
    <div>
      <button onClick={() => generateKnowledgeBase(projectId, repoUrl)}>
        Index Project
      </button>
      {task && <div>Status: {task.status}</div>}
    </div>
  )
}

Knowledge Base Architecture