feat: implement queue operations and add comprehensive test suite for…

[Kaycee276]

… task management

Description

Closes #186

PR #178 introduced a task queue with priority ordering, retry backoff logic, and a dead-letter queue, but it lacked unit tests and a few core internal functions required by the acceptance criteria. This PR fully implements the missing functions and provides a comprehensive test suite to guarantee queue behavior and stability without making any real network calls.

Changes Made

1. Task Queue Implementation Updates (lib/agent-runtime/task-queue.ts)

Added the missing queue management functions to fulfill the required behaviors:

• peekNext(agentId?: string): Retrieves the highest-priority pending task without leasing it.
• dequeue(agentId?: string): Finds the highest-priority pending task, updates its status to leased, and returns it.
• retryAll(): Iterates over all tasks currently in the dead-letter state, resetting their retries and moving them back to pending.

2. Comprehensive Test Suite (lib/task-queue/__tests__/task-queue.test.ts)

Added a new Vitest-based test suite leveraging vi.useFakeTimers() to instantly validate time-dependent logic (such as retry backoffs and FIFO sorting based on timestamps).

The test suite validates all 8 requested acceptance criteria:

• Priority Ordering: Ensures tasks are strictly dequeued in descending priority order (critical -> high -> normal -> low).
• FIFO Tie-breaking: Ensures tasks with equal priorities are dequeued in the exact order they were enqueued.
• Dead-Letter Escalation: Verifies that a task failing $N$ times (exceeding maxRetries) correctly transitions to the dead-letter queue.
• Queue Recovery: Validates that retryAll() successfully moves dead-letter tasks back to the main queue.
• Non-destructive Peeking: Tests that peekNext() returns the correct item without affecting the queue state.
• Empty State Handling: Asserts that an empty queue safely returns null on dequeue().
• POST /api/tasks Verification: Mocks Request/NextResponse to ensure the endpoint correctly processes inputs and returns a 201 status along with the task ID.
• GET /api/tasks/[id] Verification: Validates that querying a specific task ID successfully returns the current task status.

Testing Instructions

To run the newly added tests locally:

npm run test -- lib/task-queue/__tests__/task-queue.test.ts

All tests execute rapidly and entirely in-memory using mocked NextResponse boundaries to prevent any real network activity.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud