@vibescope/mcp-server 0.0.1 → 0.1.0

package/src/api-client.ts

@@ -0,0 +1,1752 @@
+/**
+ * Vibescope API Client
+ *
+ * HTTP client for communicating with the Vibescope API.
+ * All database operations are handled server-side through these endpoints.
+ */
+
+const DEFAULT_API_URL = 'https://vibescope.dev';
+
+interface ApiClientConfig {
+	apiKey: string;
+	baseUrl?: string;
+}
+
+interface ApiResponse<T> {
+	ok: boolean;
+	status: number;
+	data?: T;
+	error?: string;
+}
+
+export class VibescopeApiClient {
+	private apiKey: string;
+	private baseUrl: string;
+
+	constructor(config: ApiClientConfig) {
+		this.apiKey = config.apiKey;
+		this.baseUrl = config.baseUrl || process.env.VIBESCOPE_API_URL || DEFAULT_API_URL;
+	}
+
+	private async request<T>(method: string, path: string, body?: unknown): Promise<ApiResponse<T>> {
+		const url = `${this.baseUrl}${path}`;
+
+		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,
+					status: response.status,
+					error: data.error || `HTTP ${response.status}`
+				};
+			}
+
+			return {
+				ok: true,
+				status: response.status,
+				data
+			};
+		} catch (err) {
+			return {
+				ok: false,
+				status: 0,
+				error: err instanceof Error ? err.message : 'Network error'
+			};
+		}
+	}
+
+	// Auth endpoints
+	async validateAuth(): Promise<ApiResponse<{
+		valid: boolean;
+		user_id: string;
+		api_key_id: string;
+		key_name: string;
+	}>> {
+		return this.request('POST', '/api/mcp/auth/validate', {
+			api_key: this.apiKey
+		});
+	}
+
+	// Session endpoints
+	async startSession(params: {
+		project_id?: string;
+		git_url?: string;
+		mode?: 'lite' | 'full';
+		model?: 'opus' | 'sonnet' | 'haiku';
+		role?: 'developer' | 'validator' | 'deployer' | 'reviewer' | 'maintainer';
+	}): Promise<ApiResponse<{
+		session_started: boolean;
+		session_id?: string;
+		persona?: string;
+		role?: string;
+		project?: {
+			id: string;
+			name: string;
+			description?: string;
+			goal?: string;
+			status?: string;
+			git_url?: string;
+			agent_instructions?: string;
+			tech_stack?: string[];
+			git_workflow?: string;
+			git_main_branch?: string;
+			git_develop_branch?: string;
+			git_auto_branch?: boolean;
+		};
+		active_tasks?: Array<{
+			id: string;
+			title: string;
+			status: string;
+			priority: number;
+			progress_percentage?: number;
+			estimated_minutes?: number;
+		}>;
+		blockers?: Array<{
+			id: string;
+			description: string;
+			status: string;
+		}>;
+		next_task?: {
+			id: string;
+			title: string;
+			priority: number;
+			estimated_minutes?: number;
+		} | null;
+		directive?: string;
+		blockers_count?: number;
+		validation_count?: number;
+		project_not_found?: boolean;
+		message?: string;
+		suggestion?: {
+			action: string;
+			example: string;
+			note: string;
+		};
+		error?: string;
+	}>> {
+		return this.request('POST', '/api/mcp/sessions/start', params);
+	}
+
+	async heartbeat(sessionId: string): Promise<ApiResponse<{
+		success: boolean;
+		session_id: string;
+		timestamp: string;
+	}>> {
+		return this.request('POST', '/api/mcp/sessions/heartbeat', {
+			session_id: sessionId
+		});
+	}
+
+	async endSession(sessionId: string): Promise<ApiResponse<{
+		success: boolean;
+		ended_session_id?: string;
+		session_summary?: {
+			agent_name: string;
+			tasks_completed_this_session: number;
+			tasks_awaiting_validation: number;
+			tasks_released: number;
+		};
+		reminders?: string[];
+	}>> {
+		return this.request('POST', '/api/mcp/sessions/end', {
+			session_id: sessionId
+		});
+	}
+
+	// Project endpoints
+	async listProjects(): Promise<ApiResponse<{
+		projects: Array<{
+			id: string;
+			name: string;
+			description?: string;
+			status: string;
+			git_url?: string;
+			goal?: string;
+			tech_stack?: string[];
+		}>;
+	}>> {
+		return this.request('GET', '/api/mcp/projects');
+	}
+
+	async createProject(params: {
+		name: string;
+		description?: string;
+		goal?: string;
+		git_url?: string;
+		tech_stack?: string[];
+	}): Promise<ApiResponse<{
+		success: boolean;
+		project: {
+			id: string;
+			name: string;
+		};
+	}>> {
+		return this.request('POST', '/api/mcp/projects', params);
+	}
+
+	async getProject(projectId: string, gitUrl?: string): Promise<ApiResponse<{
+		found: boolean;
+		project?: {
+			id: string;
+			name: string;
+			description?: string;
+			goal?: string;
+			status: string;
+			git_url?: string;
+			agent_instructions?: string;
+			tech_stack?: string[];
+			git_workflow?: string;
+			git_main_branch?: string;
+			git_develop_branch?: string;
+			git_auto_branch?: boolean;
+			git_auto_tag?: boolean;
+			deployment_instructions?: string;
+		};
+		active_tasks?: Array<{
+			id: string;
+			title: string;
+			description?: string;
+			priority: number;
+			status: string;
+			progress_percentage?: number;
+			estimated_minutes?: number;
+		}>;
+		open_blockers?: Array<{
+			id: string;
+			description: string;
+		}>;
+		recent_decisions?: Array<{
+			id: string;
+			title: string;
+			description?: string;
+		}>;
+		message?: string;
+	}>> {
+		const url = gitUrl
+			? `/api/mcp/projects/${projectId}?git_url=${encodeURIComponent(gitUrl)}`
+			: `/api/mcp/projects/${projectId}`;
+		return this.request('GET', url);
+	}
+
+	async updateProject(projectId: string, updates: {
+		name?: string;
+		description?: string;
+		goal?: string;
+		git_url?: string;
+		tech_stack?: string[];
+		status?: string;
+		git_workflow?: string;
+		git_main_branch?: string;
+		git_develop_branch?: string;
+		git_auto_branch?: boolean;
+		git_auto_tag?: boolean;
+		deployment_instructions?: string;
+		agent_instructions?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		project_id: string;
+	}>> {
+		return this.request('PATCH', `/api/mcp/projects/${projectId}`, updates);
+	}
+
+	// Task endpoints
+	async getTasks(projectId: string, params?: {
+		status?: string;
+		limit?: number;
+		offset?: number;
+		include_subtasks?: boolean;
+		search_query?: string;
+		include_metadata?: boolean; // When true, returns all task fields; when false (default), only id/title/priority/status
+	}): Promise<ApiResponse<{
+		tasks: Array<{
+			id: string;
+			title: string;
+			description?: string;
+			priority: number;
+			status: string;
+			progress_percentage?: number;
+			estimated_minutes?: number;
+			started_at?: string;
+			completed_at?: string;
+			parent_task_id?: string;
+		}>;
+		total_count: number;
+		has_more: boolean;
+	}>> {
+		const queryParams = new URLSearchParams();
+		if (params?.status) queryParams.set('status', params.status);
+		if (params?.limit) queryParams.set('limit', params.limit.toString());
+		if (params?.offset) queryParams.set('offset', params.offset.toString());
+		if (params?.include_subtasks) queryParams.set('include_subtasks', 'true');
+		if (params?.search_query) queryParams.set('search_query', params.search_query);
+		if (params?.include_metadata) queryParams.set('include_metadata', 'true');
+
+		const query = queryParams.toString();
+		const url = `/api/mcp/projects/${projectId}/tasks${query ? `?${query}` : ''}`;
+		return this.request('GET', url);
+	}
+
+	async createTask(projectId: string, params: {
+		title: string;
+		description?: string;
+		priority?: number;
+		estimated_minutes?: number;
+		blocking?: boolean;
+		session_id?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		task_id: string;
+		title: string;
+		blocking?: boolean;
+		message?: string;
+	}>> {
+		return this.request('POST', `/api/mcp/projects/${projectId}/tasks`, params);
+	}
+
+	async getNextTask(projectId: string, sessionId?: string): Promise<ApiResponse<{
+		task?: {
+			id: string;
+			title: string;
+			description?: string;
+			priority: number;
+			estimated_minutes?: number;
+			blocking?: boolean;
+		} | null;
+		blocking_task?: boolean;
+		deployment_blocks_tasks?: boolean;
+		deployment?: {
+			id: string;
+			status: string;
+			env: string;
+		};
+		awaiting_validation?: Array<{
+			id: string;
+			title: string;
+		}>;
+		validation_priority?: string;
+		all_claimed?: boolean;
+		is_subtask?: boolean;
+		suggested_activity?: string;
+		directive?: string;
+		message?: string;
+		action?: string;
+	}>> {
+		const url = sessionId
+			? `/api/mcp/projects/${projectId}/next-task?session_id=${sessionId}`
+			: `/api/mcp/projects/${projectId}/next-task`;
+		return this.request('GET', url);
+	}
+
+	async getTask(taskId: string): Promise<ApiResponse<{
+		task: {
+			id: string;
+			title: string;
+			description?: string;
+			priority: number;
+			status: string;
+			progress_percentage?: number;
+			estimated_minutes?: number;
+			started_at?: string;
+			completed_at?: string;
+			git_branch?: string;
+			blocking?: boolean;
+			references?: Array<{ url: string; label?: string }>;
+			parent_task_id?: string;
+			working_agent_session_id?: string;
+		};
+	}>> {
+		return this.request('GET', `/api/mcp/tasks/${taskId}`);
+	}
+
+	async updateTask(taskId: string, updates: {
+		title?: string;
+		description?: string;
+		priority?: number;
+		status?: string;
+		progress_percentage?: number;
+		progress_note?: string;
+		estimated_minutes?: number;
+		git_branch?: string;
+		session_id?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		task_id: string;
+	}>> {
+		return this.request('PATCH', `/api/mcp/tasks/${taskId}`, updates);
+	}
+
+	async completeTask(taskId: string, params: {
+		summary?: string;
+		session_id?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		directive: string;
+		auto_continue: boolean;
+		completed_task_id: string;
+		next_task?: {
+			id: string;
+			title: string;
+			priority: number;
+			estimated_minutes?: number;
+		} | null;
+		context?: {
+			validation?: number;
+			blockers?: number;
+			deployment?: string;
+		};
+		next_action: string;
+	}>> {
+		return this.request('POST', `/api/mcp/tasks/${taskId}/complete`, params);
+	}
+
+	async deleteTask(taskId: string): Promise<ApiResponse<{
+		success: boolean;
+		deleted_id: string;
+	}>> {
+		return this.request('DELETE', `/api/mcp/tasks/${taskId}`);
+	}
+
+	// Progress endpoints
+	async logProgress(projectId: string, params: {
+		summary: string;
+		details?: string;
+		task_id?: string;
+		session_id?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		progress_id: string;
+	}>> {
+		return this.request('POST', `/api/mcp/projects/${projectId}/progress`, params);
+	}
+
+	// Git workflow endpoint
+	async getGitWorkflow(projectId: string, taskId?: string): Promise<ApiResponse<{
+		workflow: string;
+		main_branch: string;
+		develop_branch?: string | null;
+		auto_branch?: boolean;
+		auto_tag?: boolean;
+		instructions: string[];
+		task?: {
+			id: string;
+			title: string;
+			current_branch?: string;
+			suggested_branch?: string | null;
+		};
+	}>> {
+		const url = taskId
+			? `/api/mcp/projects/${projectId}/git-workflow?task_id=${taskId}`
+			: `/api/mcp/projects/${projectId}/git-workflow`;
+		return this.request('GET', url);
+	}
+
+	// ============================================================================
+	// Proxy endpoint - Generic method for all operations
+	// ============================================================================
+	async proxy<T>(operation: string, args: Record<string, unknown>, sessionContext?: {
+		session_id: string | null;
+		persona: string | null;
+		instance_id: string;
+	}): Promise<ApiResponse<T>> {
+		return this.request('POST', '/api/mcp/proxy', {
+			operation,
+			args,
+			session_context: sessionContext
+		});
+	}
+
+	// ============================================================================
+	// Blocker endpoints
+	// ============================================================================
+	async getBlockers(projectId: string, params?: {
+		status?: string;
+		limit?: number;
+		offset?: number;
+		search_query?: string;
+	}): Promise<ApiResponse<{
+		blockers: Array<{
+			id: string;
+			description: string;
+			status: string;
+			resolution_note?: string;
+			created_at: string;
+			resolved_at?: string;
+		}>;
+		total_count?: number;
+		has_more?: boolean;
+	}>> {
+		return this.proxy('get_blockers', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async addBlocker(projectId: string, description: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		blocker_id: string;
+	}>> {
+		return this.proxy('add_blocker', { project_id: projectId, description }, sessionId ? {
+			session_id: sessionId,
+			persona: null,
+			instance_id: ''
+		} : undefined);
+	}
+
+	async resolveBlocker(blockerId: string, resolutionNote?: string): Promise<ApiResponse<{
+		success: boolean;
+		blocker_id: string;
+	}>> {
+		return this.proxy('resolve_blocker', {
+			blocker_id: blockerId,
+			resolution_note: resolutionNote
+		});
+	}
+
+	async deleteBlocker(blockerId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('delete_blocker', { blocker_id: blockerId });
+	}
+
+	// ============================================================================
+	// Decision endpoints
+	// ============================================================================
+	async getDecisions(projectId: string): Promise<ApiResponse<{
+		decisions: Array<{
+			id: string;
+			title: string;
+			description: string;
+			rationale?: string;
+			alternatives_considered?: string[];
+			created_at: string;
+		}>;
+	}>> {
+		return this.proxy('get_decisions', { project_id: projectId });
+	}
+
+	async logDecision(projectId: string, params: {
+		title: string;
+		description: string;
+		rationale?: string;
+		alternatives_considered?: string[];
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		decision_id: string;
+	}>> {
+		return this.proxy('log_decision', {
+			project_id: projectId,
+			...params
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	async deleteDecision(decisionId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('delete_decision', { decision_id: decisionId });
+	}
+
+	// ============================================================================
+	// Idea endpoints
+	// ============================================================================
+	async getIdeas(projectId: string, params?: {
+		status?: string;
+		limit?: number;
+		offset?: number;
+		search_query?: string;
+	}): Promise<ApiResponse<{
+		ideas: Array<{
+			id: string;
+			title: string;
+			description?: string;
+			status: string;
+			doc_url?: string;
+			created_at: string;
+		}>;
+	}>> {
+		return this.proxy('get_ideas', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async addIdea(projectId: string, params: {
+		title: string;
+		description?: string;
+		status?: string;
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		idea_id: string;
+	}>> {
+		return this.proxy('add_idea', {
+			project_id: projectId,
+			...params
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	async updateIdea(ideaId: string, updates: {
+		title?: string;
+		description?: string;
+		status?: string;
+		doc_url?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		idea_id: string;
+	}>> {
+		return this.proxy('update_idea', {
+			idea_id: ideaId,
+			...updates
+		});
+	}
+
+	async deleteIdea(ideaId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('delete_idea', { idea_id: ideaId });
+	}
+
+	async convertIdeaToTask(ideaId: string, params?: {
+		priority?: number;
+		estimated_minutes?: number;
+		update_status?: boolean;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		task_id?: string;
+		task_title?: string;
+		idea_id?: string;
+		idea_status?: string;
+		message?: string;
+		error?: string;
+		existing_task_id?: string;
+	}>> {
+		return this.proxy('convert_idea_to_task', {
+			idea_id: ideaId,
+			...params
+		});
+	}
+
+	// ============================================================================
+	// Finding endpoints
+	// ============================================================================
+	async getFindings(projectId: string, params?: {
+		category?: string;
+		severity?: string;
+		status?: string;
+		limit?: number;
+	}): Promise<ApiResponse<{
+		findings: Array<{
+			id: string;
+			title: string;
+			description?: string;
+			category: string;
+			severity: string;
+			status: string;
+			file_path?: string;
+			line_number?: number;
+			resolution_note?: string;
+			created_at: string;
+		}>;
+	}>> {
+		return this.proxy('get_findings', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async addFinding(projectId: string, params: {
+		title: string;
+		description?: string;
+		category?: string;
+		severity?: string;
+		file_path?: string;
+		line_number?: number;
+		related_task_id?: string;
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		finding_id: string;
+	}>> {
+		return this.proxy('add_finding', {
+			project_id: projectId,
+			...params
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	async updateFinding(findingId: string, updates: {
+		title?: string;
+		description?: string;
+		severity?: string;
+		status?: string;
+		resolution_note?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		finding_id: string;
+	}>> {
+		return this.proxy('update_finding', {
+			finding_id: findingId,
+			...updates
+		});
+	}
+
+	async deleteFinding(findingId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('delete_finding', { finding_id: findingId });
+	}
+
+	// ============================================================================
+	// Milestone endpoints
+	// ============================================================================
+	async getMilestones(taskId: string): Promise<ApiResponse<{
+		milestones: Array<{
+			id: string;
+			title: string;
+			description?: string;
+			status: string;
+			order_index: number;
+			created_at: string;
+			completed_at?: string;
+		}>;
+		stats: {
+			total: number;
+			completed: number;
+			progress_percentage: number;
+		};
+	}>> {
+		return this.proxy('get_milestones', { task_id: taskId });
+	}
+
+	async addMilestone(taskId: string, params: {
+		title: string;
+		description?: string;
+		order_index?: number;
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		milestone_id: string;
+	}>> {
+		return this.proxy('add_milestone', {
+			task_id: taskId,
+			...params
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	async updateMilestone(milestoneId: string, updates: {
+		title?: string;
+		description?: string;
+		status?: string;
+		order_index?: number;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		milestone: {
+			id: string;
+			title: string;
+			status: string;
+		};
+	}>> {
+		return this.proxy('update_milestone', {
+			milestone_id: milestoneId,
+			...updates
+		});
+	}
+
+	async completeMilestone(milestoneId: string): Promise<ApiResponse<{
+		success: boolean;
+		milestone: {
+			id: string;
+			title: string;
+			status: string;
+		};
+	}>> {
+		return this.proxy('complete_milestone', { milestone_id: milestoneId });
+	}
+
+	async deleteMilestone(milestoneId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('delete_milestone', { milestone_id: milestoneId });
+	}
+
+	// ============================================================================
+	// Request endpoints
+	// ============================================================================
+	async getPendingRequests(projectId: string, sessionId?: string): Promise<ApiResponse<{
+		requests: Array<{
+			id: string;
+			request_type: string;
+			message: string;
+			created_at: string;
+		}>;
+	}>> {
+		return this.proxy('get_pending_requests', { project_id: projectId }, sessionId ? {
+			session_id: sessionId,
+			persona: null,
+			instance_id: ''
+		} : undefined);
+	}
+
+	async acknowledgeRequest(requestId: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('acknowledge_request', { request_id: requestId }, sessionId ? {
+			session_id: sessionId,
+			persona: null,
+			instance_id: ''
+		} : undefined);
+	}
+
+	async answerQuestion(requestId: string, answer: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('answer_question', {
+			request_id: requestId,
+			answer
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	// ============================================================================
+	// Validation endpoints
+	// ============================================================================
+	async getTasksAwaitingValidation(projectId: string): Promise<ApiResponse<{
+		tasks: Array<{
+			id: string;
+			title: string;
+			completed_at?: string;
+			completed_by_session_id?: string;
+		}>;
+	}>> {
+		return this.proxy('get_tasks_awaiting_validation', { project_id: projectId });
+	}
+
+	async claimValidation(taskId: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		task_id: string;
+	}>> {
+		return this.proxy('claim_validation', { task_id: taskId }, sessionId ? {
+			session_id: sessionId,
+			persona: null,
+			instance_id: ''
+		} : undefined);
+	}
+
+	async validateTask(taskId: string, params: {
+		approved: boolean;
+		validation_notes?: string;
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		approved: boolean;
+		task_id: string;
+		message?: string;
+	}>> {
+		return this.proxy('validate_task', {
+			task_id: taskId,
+			...params
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	// ============================================================================
+	// Fallback activity endpoints
+	// ============================================================================
+	async startFallbackActivity(projectId: string, activity: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		activity: string;
+		message: string;
+	}>> {
+		return this.proxy('start_fallback_activity', {
+			project_id: projectId,
+			activity
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	async stopFallbackActivity(projectId: string, summary?: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('stop_fallback_activity', {
+			project_id: projectId,
+			summary
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	async getActivityHistory(projectId: string, params?: {
+		activity_type?: string;
+		limit?: number;
+	}): Promise<ApiResponse<{
+		history: Array<{
+			id: string;
+			activity_type: string;
+			completed_at: string;
+			summary?: string;
+		}>;
+		latest_by_type: Record<string, unknown>;
+		count: number;
+	}>> {
+		return this.proxy('get_activity_history', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async getActivitySchedules(projectId: string): Promise<ApiResponse<{
+		schedules: Array<{
+			id: string;
+			activity_type: string;
+			schedule_type: string;
+			next_run_at?: string;
+			enabled: boolean;
+		}>;
+		due_activities: string[];
+		count: number;
+	}>> {
+		return this.proxy('get_activity_schedules', { project_id: projectId });
+	}
+
+	// ============================================================================
+	// Subtask endpoints
+	// ============================================================================
+	async addSubtask(parentTaskId: string, params: {
+		title: string;
+		description?: string;
+		priority?: number;
+		estimated_minutes?: number;
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		subtask_id: string;
+		parent_task_id: string;
+	}>> {
+		return this.proxy('add_subtask', {
+			parent_task_id: parentTaskId,
+			...params
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	async getSubtasks(parentTaskId: string, status?: string): Promise<ApiResponse<{
+		subtasks: Array<{
+			id: string;
+			title: string;
+			description?: string;
+			priority: number;
+			status: string;
+			progress_percentage?: number;
+			estimated_minutes?: number;
+		}>;
+		stats: {
+			total: number;
+			completed: number;
+			progress_percentage: number;
+		};
+	}>> {
+		return this.proxy('get_subtasks', {
+			parent_task_id: parentTaskId,
+			status
+		});
+	}
+
+	// ============================================================================
+	// Activity feed endpoint
+	// ============================================================================
+	async getActivityFeed(projectId: string, params?: {
+		limit?: number;
+		since?: string;
+	}): Promise<ApiResponse<{
+		activities: Array<{
+			type: string;
+			data: unknown;
+			timestamp: string;
+		}>;
+	}>> {
+		return this.proxy('get_activity_feed', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	// ============================================================================
+	// Deployment endpoints
+	// ============================================================================
+	async requestDeployment(projectId: string, params?: {
+		environment?: string;
+		version_bump?: string;
+		git_ref?: string;
+		notes?: string;
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		deployment_id: string;
+		status: string;
+	}>> {
+		return this.proxy('request_deployment', {
+			project_id: projectId,
+			...params
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	async checkDeploymentStatus(projectId: string): Promise<ApiResponse<{
+		active_deployment: boolean;
+		deployment?: {
+			id: string;
+			status: string;
+			environment: string;
+			git_ref?: string;
+			created_at: string;
+		};
+	}>> {
+		return this.proxy('check_deployment_status', { project_id: projectId });
+	}
+
+	async claimDeploymentValidation(projectId: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		deployment_id: string;
+		message: string;
+	}>> {
+		return this.proxy('claim_deployment_validation', { project_id: projectId }, sessionId ? {
+			session_id: sessionId,
+			persona: null,
+			instance_id: ''
+		} : undefined);
+	}
+
+	async reportValidation(projectId: string, params: {
+		build_passed: boolean;
+		tests_passed: boolean;
+		error_message?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		deployment_id: string;
+		status: string;
+	}>> {
+		return this.proxy('report_validation', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async startDeployment(projectId: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		deployment_id: string;
+		instructions: string;
+	}>> {
+		return this.proxy('start_deployment', { project_id: projectId }, sessionId ? {
+			session_id: sessionId,
+			persona: null,
+			instance_id: ''
+		} : undefined);
+	}
+
+	async completeDeployment(projectId: string, params: {
+		success: boolean;
+		summary?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		deployment_id: string;
+		status: string;
+	}>> {
+		return this.proxy('complete_deployment', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async cancelDeployment(projectId: string, reason?: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('cancel_deployment', {
+			project_id: projectId,
+			reason
+		});
+	}
+
+	// ============================================================================
+	// Task reference endpoints
+	// ============================================================================
+	async addTaskReference(taskId: string, url: string, label?: string): Promise<ApiResponse<{
+		success: boolean;
+		reference: { url: string; label?: string };
+	}>> {
+		return this.proxy('add_task_reference', {
+			task_id: taskId,
+			url,
+			label
+		});
+	}
+
+	async removeTaskReference(taskId: string, url: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('remove_task_reference', {
+			task_id: taskId,
+			url
+		});
+	}
+
+	// ============================================================================
+	// Knowledge base endpoint
+	// ============================================================================
+	async queryKnowledgeBase(projectId: string, params?: {
+		categories?: string[];
+		limit?: number;
+		search_query?: string;
+	}): Promise<ApiResponse<{
+		findings?: Array<{ id: string; title: string; category: string; severity: string }>;
+		decisions?: Array<{ id: string; title: string; description: string }>;
+		completed_tasks?: Array<{ id: string; title: string; completed_at: string }>;
+		resolved_blockers?: Array<{ id: string; description: string; resolution_note?: string }>;
+	}>> {
+		return this.proxy('query_knowledge_base', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	// ============================================================================
+	// Session sync endpoint
+	// ============================================================================
+	async syncSession(sessionId: string, params?: {
+		total_tokens?: number;
+		token_breakdown?: Record<string, unknown>;
+		model_usage?: Record<string, unknown>;
+	}): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('sync_session', {
+			session_id: sessionId,
+			...params
+		});
+	}
+
+	// ============================================================================
+	// Organization endpoints
+	// ============================================================================
+	async listOrganizations(): Promise<ApiResponse<{
+		organizations: Array<{
+			id: string;
+			name: string;
+			slug: string;
+			description?: string;
+			role: string;
+		}>;
+	}>> {
+		return this.proxy('list_organizations', {});
+	}
+
+	async createOrganization(params: {
+		name: string;
+		slug?: string;
+		description?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		organization: { id: string; name: string; slug: string };
+	}>> {
+		return this.proxy('create_organization', params);
+	}
+
+	async updateOrganization(organizationId: string, updates: {
+		name?: string;
+		description?: string;
+		logo_url?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		organization_id: string;
+	}>> {
+		return this.proxy('update_organization', {
+			organization_id: organizationId,
+			...updates
+		});
+	}
+
+	async deleteOrganization(organizationId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('delete_organization', { organization_id: organizationId });
+	}
+
+	async listOrgMembers(organizationId: string): Promise<ApiResponse<{
+		members: Array<{
+			user_id: string;
+			email: string;
+			role: string;
+			joined_at: string;
+		}>;
+	}>> {
+		return this.proxy('list_org_members', { organization_id: organizationId });
+	}
+
+	async inviteMember(organizationId: string, email: string, role?: string): Promise<ApiResponse<{
+		success: boolean;
+		invite_id: string;
+	}>> {
+		return this.proxy('invite_member', {
+			organization_id: organizationId,
+			email,
+			role
+		});
+	}
+
+	async updateMemberRole(organizationId: string, userId: string, role: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('update_member_role', {
+			organization_id: organizationId,
+			user_id: userId,
+			role
+		});
+	}
+
+	async removeMember(organizationId: string, userId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('remove_member', {
+			organization_id: organizationId,
+			user_id: userId
+		});
+	}
+
+	async shareProjectWithOrg(projectId: string, organizationId: string, permission?: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('share_project_with_org', {
+			project_id: projectId,
+			organization_id: organizationId,
+			permission
+		});
+	}
+
+	async unshareProject(projectId: string, organizationId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('unshare_project', {
+			project_id: projectId,
+			organization_id: organizationId
+		});
+	}
+
+	async leaveOrganization(organizationId: string): Promise<ApiResponse<{
+		success: boolean;
+		message: string;
+	}>> {
+		return this.proxy('leave_organization', { organization_id: organizationId });
+	}
+
+	async updateProjectShare(projectId: string, organizationId: string, permission: string): Promise<ApiResponse<{
+		success: boolean;
+		share: { permission: string };
+	}>> {
+		return this.proxy('update_project_share', {
+			project_id: projectId,
+			organization_id: organizationId,
+			permission
+		});
+	}
+
+	async listProjectShares(projectId: string): Promise<ApiResponse<{
+		shares: Array<{
+			id: string;
+			permission: string;
+			shared_at: string;
+			organization: { id: string; name: string; slug: string };
+		}>;
+		count: number;
+	}>> {
+		return this.proxy('list_project_shares', { project_id: projectId });
+	}
+
+	// ============================================================================
+	// Body of work endpoints
+	// ============================================================================
+	async createBodyOfWork(projectId: string, params: {
+		title: string;
+		description?: string;
+		auto_deploy_on_completion?: boolean;
+		deploy_environment?: string;
+		deploy_version_bump?: string;
+		deploy_trigger?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		body_of_work_id: string;
+	}>> {
+		return this.proxy('create_body_of_work', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async getBodyOfWork(bodyOfWorkId: string): Promise<ApiResponse<{
+		body_of_work: {
+			id: string;
+			title: string;
+			description?: string;
+			status: string;
+			auto_deploy_on_completion: boolean;
+		};
+		tasks: {
+			pre: Array<{ id: string; title: string; status: string }>;
+			core: Array<{ id: string; title: string; status: string }>;
+			post: Array<{ id: string; title: string; status: string }>;
+		};
+	}>> {
+		return this.proxy('get_body_of_work', { body_of_work_id: bodyOfWorkId });
+	}
+
+	async getBodiesOfWork(projectId: string, params?: {
+		status?: string;
+		limit?: number;
+		offset?: number;
+		search_query?: string;
+	}): Promise<ApiResponse<{
+		bodies_of_work: Array<{
+			id: string;
+			title: string;
+			description?: string;
+			status: string;
+			task_counts: { pre: number; core: number; post: number };
+		}>;
+	}>> {
+		return this.proxy('get_bodies_of_work', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async updateBodyOfWork(bodyOfWorkId: string, updates: {
+		title?: string;
+		description?: string;
+		auto_deploy_on_completion?: boolean;
+		deploy_environment?: string;
+		deploy_version_bump?: string;
+		deploy_trigger?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('update_body_of_work', {
+			body_of_work_id: bodyOfWorkId,
+			...updates
+		});
+	}
+
+	async deleteBodyOfWork(bodyOfWorkId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('delete_body_of_work', { body_of_work_id: bodyOfWorkId });
+	}
+
+	async addTaskToBodyOfWork(bodyOfWorkId: string, taskId: string, phase?: string, orderIndex?: number): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('add_task_to_body_of_work', {
+			body_of_work_id: bodyOfWorkId,
+			task_id: taskId,
+			phase,
+			order_index: orderIndex
+		});
+	}
+
+	async removeTaskFromBodyOfWork(taskId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('remove_task_from_body_of_work', { task_id: taskId });
+	}
+
+	async activateBodyOfWork(bodyOfWorkId: string): Promise<ApiResponse<{
+		success: boolean;
+		status: string;
+	}>> {
+		return this.proxy('activate_body_of_work', { body_of_work_id: bodyOfWorkId });
+	}
+
+	async addTaskDependency(bodyOfWorkId: string, taskId: string, dependsOnTaskId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('add_task_dependency', {
+			body_of_work_id: bodyOfWorkId,
+			task_id: taskId,
+			depends_on_task_id: dependsOnTaskId
+		});
+	}
+
+	async removeTaskDependency(taskId: string, dependsOnTaskId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('remove_task_dependency', {
+			task_id: taskId,
+			depends_on_task_id: dependsOnTaskId
+		});
+	}
+
+	async getTaskDependencies(params: {
+		body_of_work_id?: string;
+		task_id?: string;
+	}): Promise<ApiResponse<{
+		dependencies: Array<{
+			id: string;
+			task_id: string;
+			depends_on_task_id: string;
+			created_at: string;
+		}>;
+	}>> {
+		return this.proxy('get_task_dependencies', params);
+	}
+
+	async getNextBodyOfWorkTask(bodyOfWorkId: string): Promise<ApiResponse<{
+		task?: {
+			id: string;
+			title: string;
+			priority: number;
+			phase: string;
+		} | null;
+		message?: string;
+	}>> {
+		return this.proxy('get_next_body_of_work_task', { body_of_work_id: bodyOfWorkId });
+	}
+
+	// ============================================================================
+	// Git issues endpoints
+	// ============================================================================
+	async addGitIssue(projectId: string, params: {
+		issue_type: string;
+		branch: string;
+		target_branch?: string;
+		pr_url?: string;
+		conflicting_files?: string[];
+		error_message?: string;
+		task_id?: string;
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		git_issue_id: string;
+	}>> {
+		return this.proxy('add_git_issue', {
+			project_id: projectId,
+			...params
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	async resolveGitIssue(gitIssueId: string, params?: {
+		resolution_note?: string;
+		auto_resolved?: boolean;
+	}, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		git_issue_id: string;
+	}>> {
+		return this.proxy('resolve_git_issue', {
+			git_issue_id: gitIssueId,
+			...params
+		}, sessionId ? { session_id: sessionId, persona: null, instance_id: '' } : undefined);
+	}
+
+	async getGitIssues(projectId: string, params?: {
+		status?: string;
+		issue_type?: string;
+		branch?: string;
+		limit?: number;
+	}): Promise<ApiResponse<{
+		git_issues: Array<{
+			id: string;
+			issue_type: string;
+			branch: string;
+			target_branch?: string;
+			pr_url?: string;
+			conflicting_files?: string[];
+			error_message?: string;
+			status: string;
+			created_at: string;
+			resolved_at?: string;
+		}>;
+	}>> {
+		return this.proxy('get_git_issues', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async deleteGitIssue(gitIssueId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('delete_git_issue', { git_issue_id: gitIssueId });
+	}
+
+	// ============================================================================
+	// Cost tracking endpoints
+	// ============================================================================
+	async getCostSummary(projectId: string, params?: {
+		period?: 'daily' | 'weekly' | 'monthly';
+		limit?: number;
+	}): Promise<ApiResponse<{
+		summaries: Array<{
+			date: string;
+			total_cost: number;
+			input_tokens: number;
+			output_tokens: number;
+		}>;
+	}>> {
+		return this.proxy('get_cost_summary', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async getCostAlerts(): Promise<ApiResponse<{
+		alerts: Array<{
+			id: string;
+			threshold_amount: number;
+			threshold_period: string;
+			alert_type: string;
+			enabled: boolean;
+		}>;
+	}>> {
+		return this.proxy('get_cost_alerts', {});
+	}
+
+	async addCostAlert(params: {
+		threshold_amount: number;
+		threshold_period: 'daily' | 'weekly' | 'monthly';
+		alert_type?: 'warning' | 'critical';
+		project_id?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		alert_id: string;
+	}>> {
+		return this.proxy('add_cost_alert', params);
+	}
+
+	async updateCostAlert(alertId: string, updates: {
+		threshold_amount?: number;
+		threshold_period?: string;
+		alert_type?: string;
+		enabled?: boolean;
+	}): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('update_cost_alert', {
+			alert_id: alertId,
+			...updates
+		});
+	}
+
+	async deleteCostAlert(alertId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('delete_cost_alert', { alert_id: alertId });
+	}
+
+	async getTaskCosts(projectId: string, limit?: number): Promise<ApiResponse<{
+		task_costs: Array<{
+			task_id: string;
+			title: string;
+			total_cost: number;
+			input_tokens: number;
+			output_tokens: number;
+		}>;
+	}>> {
+		return this.proxy('get_task_costs', {
+			project_id: projectId,
+			limit
+		});
+	}
+
+	async getTokenUsage(): Promise<ApiResponse<{
+		session_tokens: number;
+		estimated_cost: number;
+	}>> {
+		return this.proxy('get_token_usage', {});
+	}
+
+	// ============================================================================
+	// Batch operation endpoints
+	// ============================================================================
+	async batchUpdateTasks(updates: Array<{
+		task_id: string;
+		status?: string;
+		priority?: number;
+		progress_percentage?: number;
+		progress_note?: string;
+	}>): Promise<ApiResponse<{
+		success: boolean;
+		updated_count: number;
+	}>> {
+		return this.proxy('batch_update_tasks', { updates });
+	}
+
+	async batchCompleteTasks(completions: Array<{
+		task_id: string;
+		summary?: string;
+	}>): Promise<ApiResponse<{
+		success: boolean;
+		completed_count: number;
+		next_task?: { id: string; title: string } | null;
+	}>> {
+		return this.proxy('batch_complete_tasks', { completions });
+	}
+
+	// ============================================================================
+	// Deployment requirements and scheduling endpoints
+	// ============================================================================
+	async addDeploymentRequirement(projectId: string, params: {
+		type: string;
+		title: string;
+		description?: string;
+		file_path?: string;
+		stage?: string;
+		blocking?: boolean;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		requirement_id: string;
+	}>> {
+		return this.proxy('add_deployment_requirement', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async getDeploymentRequirements(projectId: string, params?: {
+		status?: string;
+		stage?: string;
+	}): Promise<ApiResponse<{
+		requirements: Array<{
+			id: string;
+			type: string;
+			title: string;
+			description?: string;
+			status: string;
+			stage: string;
+		}>;
+	}>> {
+		return this.proxy('get_deployment_requirements', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async completeDeploymentRequirement(requirementId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('complete_deployment_requirement', { requirement_id: requirementId });
+	}
+
+	async scheduleDeployment(projectId: string, params: {
+		scheduled_at: string;
+		schedule_type?: string;
+		environment?: string;
+		version_bump?: string;
+		auto_trigger?: boolean;
+		notes?: string;
+		git_ref?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		schedule_id: string;
+	}>> {
+		return this.proxy('schedule_deployment', {
+			project_id: projectId,
+			...params
+		});
+	}
+
+	async getScheduledDeployments(projectId: string, includeDisabled?: boolean): Promise<ApiResponse<{
+		schedules: Array<{
+			id: string;
+			scheduled_at: string;
+			schedule_type: string;
+			environment: string;
+			version_bump: string;
+			auto_trigger: boolean;
+			enabled: boolean;
+			git_ref?: string;
+			notes?: string;
+		}>;
+		count: number;
+		due_count: number;
+	}>> {
+		return this.proxy('get_scheduled_deployments', {
+			project_id: projectId,
+			include_disabled: includeDisabled
+		});
+	}
+
+	async updateScheduledDeployment(scheduleId: string, updates: {
+		scheduled_at?: string;
+		schedule_type?: string;
+		environment?: string;
+		version_bump?: string;
+		auto_trigger?: boolean;
+		enabled?: boolean;
+		git_ref?: string;
+		notes?: string;
+	}): Promise<ApiResponse<{
+		success: boolean;
+		schedule_id: string;
+	}>> {
+		return this.proxy('update_scheduled_deployment', {
+			schedule_id: scheduleId,
+			...updates
+		});
+	}
+
+	async deleteScheduledDeployment(scheduleId: string): Promise<ApiResponse<{
+		success: boolean;
+	}>> {
+		return this.proxy('delete_scheduled_deployment', { schedule_id: scheduleId });
+	}
+
+	async triggerScheduledDeployment(scheduleId: string, sessionId?: string): Promise<ApiResponse<{
+		success: boolean;
+		deployment_id?: string;
+		schedule_id: string;
+		schedule_type: string;
+		next_scheduled_at?: string;
+		message?: string;
+	}>> {
+		return this.proxy('trigger_scheduled_deployment', { schedule_id: scheduleId }, sessionId ? {
+			session_id: sessionId,
+			persona: null,
+			instance_id: ''
+		} : undefined);
+	}
+
+	async checkDueDeployments(projectId: string): Promise<ApiResponse<{
+		due_schedules: Array<{
+			id: string;
+			scheduled_at: string;
+			environment: string;
+			version_bump: string;
+			schedule_type: string;
+		}>;
+		count: number;
+	}>> {
+		return this.proxy('check_due_deployments', { project_id: projectId });
+	}
+
+	// ============================================================================
+	// Project README endpoint
+	// ============================================================================
+	async updateProjectReadme(projectId: string, readmeContent: string): Promise<ApiResponse<{
+		success: boolean;
+		project_id: string;
+	}>> {
+		return this.proxy('update_project_readme', {
+			project_id: projectId,
+			readme_content: readmeContent
+		});
+	}
+}
+
+// Singleton instance
+let apiClient: VibescopeApiClient | null = null;
+
+export function getApiClient(): VibescopeApiClient {
+	if (!apiClient) {
+		const apiKey = process.env.VIBESCOPE_API_KEY;
+		if (!apiKey) {
+			throw new Error('VIBESCOPE_API_KEY environment variable is required');
+		}
+		apiClient = new VibescopeApiClient({ apiKey });
+	}
+	return apiClient;
+}
+
+export function initApiClient(config: ApiClientConfig): VibescopeApiClient {
+	apiClient = new VibescopeApiClient(config);
+	return apiClient;
+}