@vibescope/mcp-server 0.2.0 → 0.2.2

package/src/handlers/roles.ts

@@ -0,0 +1,208 @@
+/**
+ * Role Management Handlers
+ *
+ * Handles agent role configuration and assignment:
+ * - get_role_settings: Get role configuration for a project
+ * - update_role_settings: Update role settings for a project
+ * - set_session_role: Set the role for the current session
+ * - get_agents_by_role: Get active agents grouped by their assigned roles
+ */
+
+import type { Handler, HandlerRegistry, AgentRole } from './types.js';
+import { getApiClient } from '../api-client.js';
+
+export const getRoleSettings: Handler = async (args, _ctx) => {
+	const { project_id } = args as { project_id: string };
+
+	if (!project_id) {
+		return {
+			result: { error: 'project_id is required' },
+		};
+	}
+
+	const apiClient = getApiClient();
+	const response = await apiClient.proxy<{
+		roles: Array<{
+			role: AgentRole;
+			enabled: boolean;
+			display_name: string | null;
+			description: string | null;
+			priority_filter: number[] | null;
+			fallback_activities: string[] | null;
+			auto_assign_validation: boolean;
+			auto_assign_deployment: boolean;
+		}>;
+	}>('get_role_settings', { project_id });
+
+	if (!response.ok) {
+		return {
+			result: { error: response.error || 'Failed to get role settings' },
+		};
+	}
+
+	return { result: response.data };
+};
+
+export const updateRoleSettings: Handler = async (args, _ctx) => {
+	const {
+		project_id,
+		role,
+		enabled,
+		display_name,
+		description,
+		priority_filter,
+		fallback_activities,
+		auto_assign_validation,
+		auto_assign_deployment,
+	} = args as {
+		project_id: string;
+		role: AgentRole;
+		enabled?: boolean;
+		display_name?: string;
+		description?: string;
+		priority_filter?: number[];
+		fallback_activities?: string[];
+		auto_assign_validation?: boolean;
+		auto_assign_deployment?: boolean;
+	};
+
+	if (!project_id) {
+		return {
+			result: { error: 'project_id is required' },
+		};
+	}
+
+	if (!role) {
+		return {
+			result: { error: 'role is required' },
+		};
+	}
+
+	const apiClient = getApiClient();
+	const response = await apiClient.proxy<{
+		success: boolean;
+		role: AgentRole;
+	}>('update_role_settings', {
+		project_id,
+		role,
+		enabled,
+		display_name,
+		description,
+		priority_filter,
+		fallback_activities,
+		auto_assign_validation,
+		auto_assign_deployment,
+	});
+
+	if (!response.ok) {
+		return {
+			result: { error: response.error || 'Failed to update role settings' },
+		};
+	}
+
+	return { result: response.data };
+};
+
+export const setSessionRole: Handler = async (args, ctx) => {
+	const { role, role_config } = args as {
+		role: AgentRole;
+		role_config?: Record<string, unknown>;
+	};
+	const { session, updateSession } = ctx;
+
+	if (!role) {
+		return {
+			result: { error: 'role is required' },
+		};
+	}
+
+	const validRoles: AgentRole[] = ['developer', 'validator', 'deployer', 'reviewer', 'maintainer'];
+	if (!validRoles.includes(role)) {
+		return {
+			result: {
+				error: `Invalid role: ${role}. Must be one of: ${validRoles.join(', ')}`,
+			},
+		};
+	}
+
+	// Update local session state
+	updateSession({ currentRole: role });
+
+	// If there's an active session, update it on the server too
+	if (session.currentSessionId) {
+		const apiClient = getApiClient();
+		const response = await apiClient.proxy<{
+			success: boolean;
+			session_id: string;
+			role: AgentRole;
+		}>('set_session_role', {
+			session_id: session.currentSessionId,
+			role,
+			role_config,
+		});
+
+		if (!response.ok) {
+			return {
+				result: { error: response.error || 'Failed to update session role' },
+			};
+		}
+
+		return {
+			result: {
+				success: true,
+				session_id: session.currentSessionId,
+				role,
+				message: `Session role updated to ${role}. Task filtering and fallback suggestions will now be optimized for this role.`,
+			},
+		};
+	}
+
+	return {
+		result: {
+			success: true,
+			role,
+			message: `Local role set to ${role}. Start a session to persist this role.`,
+		},
+	};
+};
+
+export const getAgentsByRole: Handler = async (args, _ctx) => {
+	const { project_id } = args as { project_id: string };
+
+	if (!project_id) {
+		return {
+			result: { error: 'project_id is required' },
+		};
+	}
+
+	const apiClient = getApiClient();
+	const response = await apiClient.proxy<{
+		agents_by_role: Record<AgentRole, Array<{
+			session_id: string;
+			agent_name: string;
+			status: string;
+			current_task_id: string | null;
+			current_task_title: string | null;
+			last_synced_at: string;
+		}>>;
+		total_active: number;
+	}>('get_agents_by_role', { project_id });
+
+	if (!response.ok) {
+		return {
+			result: { error: response.error || 'Failed to get agents by role' },
+		};
+	}
+
+	return { result: response.data };
+};
+
+/**
+ * Role handlers registry
+ */
+export const roleHandlers: HandlerRegistry = {
+	get_role_settings: getRoleSettings,
+	update_role_settings: updateRoleSettings,
+	set_session_role: setSessionRole,
+	get_agents_by_role: getAgentsByRole,
+};

package/src/handlers/session.test.ts

@@ -526,4 +526,51 @@ describe('startWorkSession', () => {
 		expect(result.result).toHaveProperty('next_task');
 		expect((result.result as { next_task: { id: string } }).next_task.id).toBe('task-1');
 	});
+
+	it('should include pending_requests when available in full mode', async () => {
+		const ctx = createMockContext({ sessionId: null });
+		const mockRequests = [
+			{ id: 'req-1', request_type: 'question', message: 'What is the status?', created_at: '2026-01-14T10:00:00Z' },
+			{ id: 'req-2', request_type: 'instruction', message: 'Please prioritize task X', created_at: '2026-01-14T11:00:00Z' },
+		];
+		mockApiClient.startSession.mockResolvedValue({
+			ok: true,
+			data: {
+				session_started: true,
+				session_id: 'new-session-123',
+				persona: 'Wave',
+				role: 'developer',
+				project: { id: 'project-123', name: 'Test Project' },
+				pending_requests: mockRequests,
+			},
+		});
+
+		const result = await startWorkSession({ project_id: 'project-123', mode: 'full' }, ctx);
+
+		expect(result.result).toHaveProperty('pending_requests');
+		expect(result.result).toHaveProperty('pending_requests_count', 2);
+		const pendingRequests = (result.result as { pending_requests: typeof mockRequests }).pending_requests;
+		expect(pendingRequests.length).toBe(2);
+		expect(pendingRequests[0].request_type).toBe('question');
+	});
+
+	it('should not include pending_requests when empty', async () => {
+		const ctx = createMockContext({ sessionId: null });
+		mockApiClient.startSession.mockResolvedValue({
+			ok: true,
+			data: {
+				session_started: true,
+				session_id: 'new-session-123',
+				persona: 'Wave',
+				role: 'developer',
+				project: { id: 'project-123', name: 'Test Project' },
+				pending_requests: [],
+			},
+		});
+
+		const result = await startWorkSession({ project_id: 'project-123', mode: 'full' }, ctx);
+
+		expect(result.result).not.toHaveProperty('pending_requests');
+		expect(result.result).not.toHaveProperty('pending_requests_count');
+	});
 });

package/src/handlers/session.ts

@@ -10,22 +10,47 @@
  */
 
 import type { Handler, HandlerRegistry, TokenUsage } from './types.js';
+import { parseArgs, createEnumValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 
+const VALID_MODES = ['lite', 'full'] as const;
+const VALID_MODELS = ['opus', 'sonnet', 'haiku'] as const;
+const VALID_ROLES = ['developer', 'validator', 'deployer', 'reviewer', 'maintainer'] as const;
+
+type SessionMode = typeof VALID_MODES[number];
+type SessionModel = typeof VALID_MODELS[number];
+type SessionRole = typeof VALID_ROLES[number];
+
+// Argument schemas for type-safe parsing
+const startWorkSessionSchema = {
+	project_id: { type: 'string' as const },
+	git_url: { type: 'string' as const },
+	mode: { type: 'string' as const, default: 'lite', validate: createEnumValidator(VALID_MODES) },
+	model: { type: 'string' as const, validate: createEnumValidator(VALID_MODELS) },
+	role: { type: 'string' as const, default: 'developer', validate: createEnumValidator(VALID_ROLES) },
+};
+
+const heartbeatSchema = {
+	session_id: { type: 'string' as const },
+	current_worktree_path: { type: 'string' as const },
+};
+
+const endWorkSessionSchema = {
+	session_id: { type: 'string' as const },
+};
+
+const getHelpSchema = {
+	topic: { type: 'string' as const, required: true as const },
+};
+
 export const startWorkSession: Handler = async (args, ctx) => {
-	const { project_id, git_url, mode = 'lite', model, role = 'developer' } = args as {
-		project_id?: string;
-		git_url?: string;
-		mode?: 'lite' | 'full';
-		model?: 'opus' | 'sonnet' | 'haiku';
-		role?: 'developer' | 'validator' | 'deployer' | 'reviewer' | 'maintainer';
-	};
+	const { project_id, git_url, mode, model, role } = parseArgs(args, startWorkSessionSchema);
 
 	const { session, updateSession } = ctx;
 
 	// Reset token tracking for new session with model info
 	const normalizedModel = model ? model.toLowerCase().replace(/^claude[- ]*/i, '') : null;
-	const validModel = normalizedModel && ['opus', 'sonnet', 'haiku'].includes(normalizedModel)
+	const validModel = normalizedModel && VALID_MODELS.includes(normalizedModel as SessionModel)
 		? normalizedModel
 		: null;
 
@@ -52,9 +77,9 @@ export const startWorkSession: Handler = async (args, ctx) => {
 	const response = await apiClient.startSession({
 		project_id,
 		git_url,
-		mode,
-		model,
-		role
+		mode: mode as SessionMode,
+		model: model as SessionModel | undefined,
+		role: role as SessionRole
 	});
 
 	if (!response.ok) {
@@ -80,22 +105,40 @@ export const startWorkSession: Handler = async (args, ctx) => {
 		});
 	}
 
-	// Build result with directive at top for visibility
+	// Check for urgent questions - these MUST be handled first
+	const hasUrgentQuestions = data.URGENT_QUESTIONS || (data.pending_requests && data.pending_requests.length > 0);
+
+	// Build result - URGENT_QUESTIONS at absolute top for maximum visibility
 	const result: Record<string, unknown> = {
 		session_started: true,
-		directive: data.directive || 'ACTION_REQUIRED: Start working immediately.',
-		auto_continue: true,
-		session_id: data.session_id,
-		persona: data.persona,
-		role: data.role,
-		project: data.project,
 	};
 
+	// URGENT_QUESTIONS must be the FIRST thing the agent sees
+	if (data.URGENT_QUESTIONS) {
+		result.URGENT_QUESTIONS = data.URGENT_QUESTIONS;
+	}
+
+	// Directive comes right after urgent questions
+	result.directive = data.directive || 'ACTION_REQUIRED: Start working immediately.';
+	result.auto_continue = true;
+
+	// Session info
+	result.session_id = data.session_id;
+	result.persona = data.persona;
+	result.role = data.role;
+	result.project = data.project;
+
 	// Add task data
 	if (data.next_task) {
 		result.next_task = data.next_task;
 	}
 
+	// Add pending requests (questions from user) - these take priority
+	if (data.pending_requests && data.pending_requests.length > 0) {
+		result.pending_requests = data.pending_requests;
+		result.pending_requests_count = data.pending_requests.length;
+	}
+
 	// Add active tasks for full mode
 	if (data.active_tasks) {
 		result.active_tasks = data.active_tasks;
@@ -128,8 +171,13 @@ export const startWorkSession: Handler = async (args, ctx) => {
 		};
 	}
 
-	// Add next action at end
-	if (data.next_task) {
+	// Add next action at end - pending requests take priority over tasks
+	if (hasUrgentQuestions) {
+		const firstQuestion = data.URGENT_QUESTIONS?.requests?.[0] || data.pending_requests?.[0];
+		result.next_action = firstQuestion
+			? `answer_question(request_id: "${firstQuestion.id}", answer: "...")`
+			: 'Check pending_requests and respond using answer_question(request_id, answer)';
+	} else if (data.next_task) {
 		result.next_action = `update_task(task_id: "${data.next_task.id}", status: "in_progress")`;
 	} else if (data.project) {
 		result.next_action = `start_fallback_activity(project_id: "${data.project.id}", activity: "code_review")`;
@@ -139,10 +187,7 @@ export const startWorkSession: Handler = async (args, ctx) => {
 };
 
 export const heartbeat: Handler = async (args, ctx) => {
-	const { session_id, current_worktree_path } = args as {
-		session_id?: string;
-		current_worktree_path?: string | null;
-	};
+	const { session_id, current_worktree_path } = parseArgs(args, heartbeatSchema);
 	const { session } = ctx;
 	const targetSession = session_id || session.currentSessionId;
 
@@ -186,7 +231,7 @@ export const heartbeat: Handler = async (args, ctx) => {
 };
 
 export const endWorkSession: Handler = async (args, ctx) => {
-	const { session_id } = args as { session_id?: string };
+	const { session_id } = parseArgs(args, endWorkSessionSchema);
 	const { session, updateSession } = ctx;
 	const targetSession = session_id || session.currentSessionId;
 
@@ -251,7 +296,7 @@ export const endWorkSession: Handler = async (args, ctx) => {
 };
 
 export const getHelp: Handler = async (args, _ctx) => {
-	const { topic } = args as { topic: string };
+	const { topic } = parseArgs(args, getHelpSchema);
 
 	const apiClient = getApiClient();
 	const response = await apiClient.getHelpTopic(topic);

package/src/handlers/sprints.test.ts

@@ -99,30 +99,36 @@ describe('createSprint', () => {
 		).rejects.toThrow(ValidationError);
 	});
 
-	it('should throw error for invalid start_date format', async () => {
+	it('should return error for invalid start_date format', async () => {
 		const ctx = createMockContext();
 
-		await expect(
-			createSprint({
-				project_id: VALID_UUID,
-				title: 'Sprint 1',
-				start_date: 'invalid',
-				end_date: '2025-01-14'
-			}, ctx)
-		).rejects.toThrow('Invalid start_date format');
+		const result = await createSprint({
+			project_id: VALID_UUID,
+			title: 'Sprint 1',
+			start_date: 'invalid',
+			end_date: '2025-01-14'
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Invalid start_date format. Use YYYY-MM-DD',
+		});
 	});
 
-	it('should throw error when end_date is before start_date', async () => {
+	it('should return error when end_date is before start_date', async () => {
 		const ctx = createMockContext();
 
-		await expect(
-			createSprint({
-				project_id: VALID_UUID,
-				title: 'Sprint 1',
-				start_date: '2025-01-14',
-				end_date: '2025-01-01'
-			}, ctx)
-		).rejects.toThrow('end_date must be on or after start_date');
+		const result = await createSprint({
+			project_id: VALID_UUID,
+			title: 'Sprint 1',
+			start_date: '2025-01-14',
+			end_date: '2025-01-01'
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'end_date must be on or after start_date',
+		});
 	});
 
 	it('should create sprint successfully', async () => {
@@ -180,21 +186,24 @@ describe('createSprint', () => {
 		);
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.proxy.mockResolvedValue({
 			ok: false,
 			error: 'Database error',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			createSprint({
-				project_id: VALID_UUID,
-				title: 'Sprint 1',
-				start_date: '2025-01-01',
-				end_date: '2025-01-14',
-			}, ctx)
-		).rejects.toThrow('Failed to create sprint: Database error');
+		const result = await createSprint({
+			project_id: VALID_UUID,
+			title: 'Sprint 1',
+			start_date: '2025-01-01',
+			end_date: '2025-01-14',
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Database error',
+		});
 	});
 });
 
@@ -238,16 +247,19 @@ describe('updateSprint', () => {
 		});
 	});
 
-	it('should throw error when API call fails', async () => {
+	it('should return error when API call fails', async () => {
 		mockApiClient.proxy.mockResolvedValue({
 			ok: false,
 			error: 'Sprint not found',
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			updateSprint({ sprint_id: VALID_UUID, title: 'Test' }, ctx)
-		).rejects.toThrow('Failed to update sprint: Sprint not found');
+		const result = await updateSprint({ sprint_id: VALID_UUID, title: 'Test' }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'Sprint not found',
+		});
 	});
 });
 
@@ -417,16 +429,19 @@ describe('startSprint', () => {
 		});
 	});
 
-	it('should throw error when sprint not in planning', async () => {
+	it('should return error when sprint not in planning', async () => {
 		mockApiClient.proxy.mockResolvedValue({
 			ok: false,
 			error: "Cannot start sprint in 'active' status",
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			startSprint({ sprint_id: VALID_UUID }, ctx)
-		).rejects.toThrow("Cannot start sprint in 'active' status");
+		const result = await startSprint({ sprint_id: VALID_UUID }, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: "Cannot start sprint in 'active' status",
+		});
 	});
 });
 
@@ -514,16 +529,19 @@ describe('addTaskToSprint', () => {
 		).rejects.toThrow(ValidationError);
 	});
 
-	it('should throw error for negative story_points', async () => {
+	it('should return error for negative story_points', async () => {
 		const ctx = createMockContext();
 
-		await expect(
-			addTaskToSprint({
-				sprint_id: VALID_UUID,
-				task_id: VALID_UUID_2,
-				story_points: -1,
-			}, ctx)
-		).rejects.toThrow('story_points must be a non-negative integer');
+		const result = await addTaskToSprint({
+			sprint_id: VALID_UUID,
+			task_id: VALID_UUID_2,
+			story_points: -1,
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: 'story_points must be a non-negative integer',
+		});
 	});
 
 	it('should add task to sprint with story points', async () => {
@@ -554,19 +572,22 @@ describe('addTaskToSprint', () => {
 		});
 	});
 
-	it('should throw error when sprint not in planning', async () => {
+	it('should return error when sprint not in planning', async () => {
 		mockApiClient.proxy.mockResolvedValue({
 			ok: false,
 			error: "Cannot add tasks to sprint in 'active' status",
 		});
 		const ctx = createMockContext();
 
-		await expect(
-			addTaskToSprint({
-				sprint_id: VALID_UUID,
-				task_id: VALID_UUID_2,
-			}, ctx)
-		).rejects.toThrow("Cannot add tasks to sprint in 'active' status");
+		const result = await addTaskToSprint({
+			sprint_id: VALID_UUID,
+			task_id: VALID_UUID_2,
+		}, ctx);
+
+		expect(result.isError).toBe(true);
+		expect(result.result).toMatchObject({
+			error: "Cannot add tasks to sprint in 'active' status",
+		});
 	});
 });