# Issue #167: Runner jobs CRUD and queue submission

## Objective

Implement runner-jobs module for job lifecycle management and queue submission, integrating with BullMQ for async job processing.

## Prerequisites

- #164 (Database schema) - RunnerJob model available ✅
- #165 (BullMQ module) - BullMqService available for queue submission ✅

## Approach

1. Review existing CRUD patterns (tasks, events modules)
2. Review RunnerJob schema and BullMqService interface
3. Follow TDD: Write tests first (RED phase)
4. Implement service layer with Prisma + BullMQ integration (GREEN phase)
5. Implement controller layer (GREEN phase)
6. Refactor and optimize (REFACTOR phase)
7. Run quality gates (typecheck, lint, build, test)

## API Endpoints

- POST /runner-jobs - Create and queue a new job
- GET /runner-jobs - List jobs (with filters)
- GET /runner-jobs/:id - Get job details
- POST /runner-jobs/:id/cancel - Cancel a running job
- POST /runner-jobs/:id/retry - Retry a failed job

## Progress

- [x] Review existing patterns and dependencies
- [x] Create DTOs (CreateJobDto, QueryJobsDto)
- [x] Write service tests (RED phase)
- [x] Implement service with Prisma + BullMQ (GREEN phase)
- [x] Write controller tests (RED phase)
- [x] Implement controller (GREEN phase)
- [x] Create module configuration
- [x] Run quality gates (typecheck, lint, build, test)
- [x] Commit changes

## Quality Gates Results

- Typecheck: ✅ PASSED
- Lint: ✅ PASSED (auto-fixed formatting)
- Build: ✅ PASSED
- Tests: ✅ PASSED (24/24 tests passing)

## Testing

- Unit tests for RunnerJobsService
- Unit tests for RunnerJobsController
- Mock BullMqService for queue operations
- Mock Prisma for database operations
- Target: ≥85% coverage

## Implementation Summary

**Files Created:**

- apps/api/src/runner-jobs/dto/create-job.dto.ts - Job creation DTO
- apps/api/src/runner-jobs/dto/query-jobs.dto.ts - Job query DTO
- apps/api/src/runner-jobs/dto/index.ts - DTO barrel export
- apps/api/src/runner-jobs/runner-jobs.service.ts - Service implementation
- apps/api/src/runner-jobs/runner-jobs.service.spec.ts - Service tests (18 tests)
- apps/api/src/runner-jobs/runner-jobs.controller.ts - Controller implementation
- apps/api/src/runner-jobs/runner-jobs.controller.spec.ts - Controller tests (6 tests)
- apps/api/src/runner-jobs/runner-jobs.module.ts - Module configuration
- apps/api/src/runner-jobs/index.ts - Module barrel export

**Key Implementation Details:**

1. Used Prisma relations (workspace.connect, agentTask.connect) for foreign keys
2. Optional fields only included when present (result, agentTaskId)
3. BullMQ integration for async job processing via QUEUE_NAMES.RUNNER
4. Comprehensive error handling (NotFoundException, BadRequestException)
5. Following existing patterns from tasks/events modules

**Test Coverage:**

- Service: 18 tests covering create, findAll, findOne, cancel, retry
- Controller: 6 tests covering all endpoints
- Total: 24 tests, all passing

**Token Usage Estimate:** ~76,000 tokens

## Notes

- Followed existing CRUD patterns from tasks/events modules
- Used DTOs for validation
- Integrated with BullMqService for queue submission
- Used Prisma for all database operations
- Followed PDA-friendly language principles in responses