@vibescope/mcp-server 0.3.0 → 0.3.3

package/src/api-client.test.ts

@@ -23,11 +23,14 @@ const mockFetch = vi.fn();
 global.fetch = mockFetch;
 
 // Helper to create mock response
-function createMockResponse(data: unknown, ok = true, status = 200) {
+function createMockResponse(data: unknown, ok = true, status = 200, headers?: Record<string, string>) {
 	return {
 		ok,
 		status,
 		json: vi.fn().mockResolvedValue(data),
+		headers: {
+			get: (name: string) => headers?.[name] ?? null,
+		},
 	};
 }
 
@@ -36,12 +39,21 @@ function createNetworkError(message: string) {
 	return new Error(message);
 }
 
+// Fast retry config for tests (1ms delays instead of 1000ms)
+const FAST_RETRY_CONFIG = {
+	maxRetries: 3,
+	baseDelayMs: 1,
+	maxDelayMs: 10,
+	retryStatusCodes: [429, 503, 504],
+};
+
 describe('VibescopeApiClient', () => {
 	let client: VibescopeApiClient;
 
 	beforeEach(() => {
 		vi.clearAllMocks();
-		client = new VibescopeApiClient({ apiKey: 'test-api-key' });
+		// Use fast retry config so tests don't take forever
+		client = new VibescopeApiClient({ apiKey: 'test-api-key', retry: FAST_RETRY_CONFIG });
 	});
 
 	afterEach(() => {
@@ -181,29 +193,33 @@ describe('VibescopeApiClient', () => {
 			});
 		});
 
-		it('should handle network errors', async () => {
+		it('should handle network errors after retries', async () => {
 			mockFetch.mockRejectedValue(createNetworkError('Network request failed'));
 
 			const result = await client.validateAuth();
 
+			// Network errors are retried, so 4 attempts total (1 initial + 3 retries)
+			expect(mockFetch).toHaveBeenCalledTimes(4);
 			expect(result).toEqual({
 				ok: false,
 				status: 0,
 				error: 'Network request failed',
 			});
-		});
+		}, 30000);
 
-		it('should handle non-Error exceptions', async () => {
+		it('should handle non-Error exceptions after retries', async () => {
 			mockFetch.mockRejectedValue('String error');
 
 			const result = await client.validateAuth();
 
+			// Non-Error exceptions are converted to Error('Network error') and retried
+			expect(mockFetch).toHaveBeenCalledTimes(4);
 			expect(result).toEqual({
 				ok: false,
 				status: 0,
 				error: 'Network error',
 			});
-		});
+		}, 30000);
 	});
 
 	// ============================================================================
@@ -693,31 +709,142 @@ describe('VibescopeApiClient', () => {
 	// ============================================================================
 
 	describe('error handling edge cases', () => {
-		it('should handle JSON parse error in response', async () => {
+		it('should handle JSON parse error in response after retries', async () => {
 			mockFetch.mockResolvedValue({
 				ok: true,
 				status: 200,
 				json: vi.fn().mockRejectedValue(new SyntaxError('Invalid JSON')),
+				headers: { get: () => null },
 			});
 
 			const result = await client.validateAuth();
 
+			// JSON parse errors are treated as network errors and retried
+			expect(mockFetch).toHaveBeenCalledTimes(4);
 			expect(result.ok).toBe(false);
 			expect(result.error).toContain('Invalid JSON');
-		});
+		}, 30000);
 
-		it('should handle timeout errors', async () => {
+		it('should handle timeout errors after retries', async () => {
 			const timeoutError = new Error('Request timeout');
 			timeoutError.name = 'AbortError';
 			mockFetch.mockRejectedValue(timeoutError);
 
 			const result = await client.validateAuth();
 
+			// Timeout errors are retried
+			expect(mockFetch).toHaveBeenCalledTimes(4);
 			expect(result).toEqual({
 				ok: false,
 				status: 0,
 				error: 'Request timeout',
 			});
+		}, 30000);
+	});
+
+	// ============================================================================
+	// Retry Logic Tests
+	// ============================================================================
+
+	describe('retry logic', () => {
+		it('should retry on 429 status code', async () => {
+			// First two calls return 429, third succeeds
+			mockFetch
+				.mockResolvedValueOnce(createMockResponse({ error: 'Rate limited' }, false, 429))
+				.mockResolvedValueOnce(createMockResponse({ error: 'Rate limited' }, false, 429))
+				.mockResolvedValueOnce(createMockResponse({ valid: true }, true, 200));
+
+			const result = await client.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledTimes(3);
+			expect(result.ok).toBe(true);
+		});
+
+		it('should retry on 503 status code', async () => {
+			mockFetch
+				.mockResolvedValueOnce(createMockResponse({ error: 'Service unavailable' }, false, 503))
+				.mockResolvedValueOnce(createMockResponse({ valid: true }, true, 200));
+
+			const result = await client.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledTimes(2);
+			expect(result.ok).toBe(true);
+		});
+
+		it('should retry on 504 status code', async () => {
+			mockFetch
+				.mockResolvedValueOnce(createMockResponse({ error: 'Gateway timeout' }, false, 504))
+				.mockResolvedValueOnce(createMockResponse({ valid: true }, true, 200));
+
+			const result = await client.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledTimes(2);
+			expect(result.ok).toBe(true);
+		});
+
+		it('should not retry on non-retryable status codes (400)', async () => {
+			mockFetch.mockResolvedValueOnce(createMockResponse({ error: 'Bad request' }, false, 400));
+
+			const result = await client.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledTimes(1);
+			expect(result.ok).toBe(false);
+			expect(result.status).toBe(400);
+		});
+
+		it('should not retry on non-retryable status codes (401)', async () => {
+			mockFetch.mockResolvedValueOnce(createMockResponse({ error: 'Unauthorized' }, false, 401));
+
+			const result = await client.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledTimes(1);
+			expect(result.ok).toBe(false);
+			expect(result.status).toBe(401);
 		});
+
+		it('should not retry on non-retryable status codes (500)', async () => {
+			mockFetch.mockResolvedValueOnce(createMockResponse({ error: 'Server error' }, false, 500));
+
+			const result = await client.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledTimes(1);
+			expect(result.ok).toBe(false);
+			expect(result.status).toBe(500);
+		});
+
+		it('should stop after max retries (3)', async () => {
+			// All 4 attempts (1 initial + 3 retries) return 429
+			mockFetch.mockResolvedValue(createMockResponse({ error: 'Rate limited' }, false, 429));
+
+			const result = await client.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledTimes(4); // 1 initial + 3 retries
+			expect(result.ok).toBe(false);
+			expect(result.status).toBe(429);
+			// API error message takes precedence over generic retry message
+			expect(result.error).toBe('Rate limited');
+		}, 30000);
+
+		it('should retry on network errors', async () => {
+			mockFetch
+				.mockRejectedValueOnce(new Error('Network error'))
+				.mockResolvedValueOnce(createMockResponse({ valid: true }, true, 200));
+
+			const result = await client.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledTimes(2);
+			expect(result.ok).toBe(true);
+		}, 10000);
+
+		it('should return last error after all retries exhausted on network failure', async () => {
+			mockFetch.mockRejectedValue(new Error('Connection refused'));
+
+			const result = await client.validateAuth();
+
+			expect(mockFetch).toHaveBeenCalledTimes(4);
+			expect(result.ok).toBe(false);
+			expect(result.status).toBe(0);
+			expect(result.error).toBe('Connection refused');
+		}, 30000);
 	});
 });

package/src/api-client.ts

@@ -7,9 +7,23 @@
 
 const DEFAULT_API_URL = 'https://vibescope.dev';
 
+// Retry configuration defaults
+const DEFAULT_RETRY_STATUS_CODES = [429, 503, 504];
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_BASE_DELAY_MS = 1000;
+const DEFAULT_MAX_DELAY_MS = 30000;
+
+interface RetryConfig {
+	maxRetries?: number;
+	baseDelayMs?: number;
+	maxDelayMs?: number;
+	retryStatusCodes?: number[];
+}
+
 interface ApiClientConfig {
 	apiKey: string;
 	baseUrl?: string;
+	retry?: RetryConfig;
 }
 
 interface ApiResponse<T> {
@@ -19,51 +33,134 @@ interface ApiResponse<T> {
 	error?: string;
 }
 
+/**
+ * Calculate delay for exponential backoff with jitter
+ */
+function calculateBackoffDelay(
+	attempt: number,
+	baseDelayMs: number,
+	maxDelayMs: number,
+	retryAfter?: number
+): number {
+	// If Retry-After header is present, use it (in seconds)
+	if (retryAfter !== undefined && retryAfter > 0) {
+		return Math.min(retryAfter * 1000, maxDelayMs);
+	}
+	// Exponential backoff: base * 2^attempt with jitter
+	const exponentialDelay = baseDelayMs * Math.pow(2, attempt);
+	const jitter = Math.random() * 0.3 * exponentialDelay; // 0-30% jitter
+	return Math.min(exponentialDelay + jitter, maxDelayMs);
+}
+
+/**
+ * Sleep for a specified duration
+ */
+function sleep(ms: number): Promise<void> {
+	return new Promise(resolve => setTimeout(resolve, ms));
+}
+
 export class VibescopeApiClient {
 	private apiKey: string;
 	private baseUrl: string;
+	private retryConfig: Required<RetryConfig>;
 
 	constructor(config: ApiClientConfig) {
 		this.apiKey = config.apiKey;
 		this.baseUrl = config.baseUrl || process.env.VIBESCOPE_API_URL || DEFAULT_API_URL;
+		this.retryConfig = {
+			maxRetries: config.retry?.maxRetries ?? DEFAULT_MAX_RETRIES,
+			baseDelayMs: config.retry?.baseDelayMs ?? DEFAULT_BASE_DELAY_MS,
+			maxDelayMs: config.retry?.maxDelayMs ?? DEFAULT_MAX_DELAY_MS,
+			retryStatusCodes: config.retry?.retryStatusCodes ?? DEFAULT_RETRY_STATUS_CODES,
+		};
 	}
 
 	private async request<T>(method: string, path: string, body?: unknown): Promise<ApiResponse<T>> {
 		const url = `${this.baseUrl}${path}`;
+		const { maxRetries, baseDelayMs, maxDelayMs, retryStatusCodes } = this.retryConfig;
+		let lastError: Error | null = null;
+		let lastResponse: Response | null = null;
+
+		for (let attempt = 0; attempt <= maxRetries; attempt++) {
+			try {
+				const response = await fetch(url, {
+					method,
+					headers: {
+						'Content-Type': 'application/json',
+						'X-API-Key': this.apiKey
+					},
+					body: body ? JSON.stringify(body) : undefined
+				});
+
+				// Check if we should retry this status code
+				if (retryStatusCodes.includes(response.status) && attempt < maxRetries) {
+					lastResponse = response;
+					// Parse Retry-After header if present (can be seconds or HTTP-date)
+					const retryAfterHeader = response.headers.get('Retry-After');
+					let retryAfter: number | undefined;
+					if (retryAfterHeader) {
+						const seconds = parseInt(retryAfterHeader, 10);
+						if (!isNaN(seconds)) {
+							retryAfter = seconds;
+						}
+					}
+					const delay = calculateBackoffDelay(attempt, baseDelayMs, maxDelayMs, retryAfter);
+					await sleep(delay);
+					continue;
+				}
+
+				const data = await response.json();
+
+				if (!response.ok) {
+					return {
+						ok: false,
+						status: response.status,
+						error: data.error || `HTTP ${response.status}`,
+						data // Include full response data for additional error context
+					};
+				}
 
-		try {
-			const response = await fetch(url, {
-				method,
-				headers: {
-					'Content-Type': 'application/json',
-					'X-API-Key': this.apiKey
-				},
-				body: body ? JSON.stringify(body) : undefined
-			});
-
-			const data = await response.json();
-
-			if (!response.ok) {
 				return {
-					ok: false,
+					ok: true,
 					status: response.status,
-					error: data.error || `HTTP ${response.status}`,
-					data // Include full response data for additional error context
+					data
 				};
+			} catch (err) {
+				lastError = err instanceof Error ? err : new Error('Network error');
+				// Retry on network errors (connection failures, timeouts)
+				if (attempt < maxRetries) {
+					const delay = calculateBackoffDelay(attempt, baseDelayMs, maxDelayMs);
+					await sleep(delay);
+					continue;
+				}
 			}
+		}
 
-			return {
-				ok: true,
-				status: response.status,
-				data
-			};
-		} catch (err) {
-			return {
-				ok: false,
-				status: 0,
-				error: err instanceof Error ? err.message : 'Network error'
-			};
+		// All retries exhausted
+		if (lastResponse) {
+			// We had a response but it was a retryable error status
+			try {
+				const data = await lastResponse.json();
+				return {
+					ok: false,
+					status: lastResponse.status,
+					error: data.error || `HTTP ${lastResponse.status} after ${maxRetries} retries`,
+					data
+				};
+			} catch {
+				return {
+					ok: false,
+					status: lastResponse.status,
+					error: `HTTP ${lastResponse.status} after ${maxRetries} retries`
+				};
+			}
 		}
+
+		return {
+			ok: false,
+			status: 0,
+			error: lastError?.message || 'Network error after retries'
+		};
 	}
 
 	// Auth endpoints
@@ -87,6 +184,7 @@ export class VibescopeApiClient {
 		role?: string; // Open-ended - any role name accepted
 		hostname?: string; // Machine hostname for worktree tracking
 		agent_type?: string; // Open-ended - any agent type accepted
+		agent_name?: string; // Explicit name for cloud/remote agents (skips persona pool)
 	}): Promise<ApiResponse<{
 		session_started: boolean;
 		session_id?: string;