@vibescope/mcp-server 0.0.1

package/src/handlers/deployment.ts

@@ -0,0 +1,1289 @@
+/**
+ * Deployment Handlers
+ *
+ * Handles deployment coordination and requirements:
+ * - request_deployment
+ * - claim_deployment_validation
+ * - report_validation
+ * - check_deployment_status
+ * - start_deployment
+ * - complete_deployment
+ * - cancel_deployment
+ * - add_deployment_requirement
+ * - complete_deployment_requirement
+ * - get_deployment_requirements
+ */
+
+import type { Handler, HandlerRegistry } from './types.js';
+import {
+	ValidationError,
+	validateRequired,
+	validateUUID,
+	validateEnvironment,
+} from '../validators.js';
+
+export const requestDeployment: Handler = async (args, ctx) => {
+	const { project_id, environment = 'production', version_bump = 'patch', notes, git_ref } = args as {
+		project_id: string;
+		environment?: string;
+		version_bump?: 'patch' | 'minor' | 'major';
+		notes?: string;
+		git_ref?: string;
+	};
+
+	const { supabase, session } = ctx;
+	const currentSessionId = session.currentSessionId;
+
+	validateRequired(project_id, 'project_id');
+	validateUUID(project_id, 'project_id');
+	validateEnvironment(environment);
+
+	if (version_bump && !['patch', 'minor', 'major'].includes(version_bump)) {
+		throw new ValidationError('Invalid version_bump value', {
+			field: 'version_bump',
+			validValues: ['patch', 'minor', 'major'],
+			hint: 'Must be one of: patch, minor, major',
+		});
+	}
+
+	// Check for existing active deployment
+	const { data: existingDeployment } = await supabase
+		.from('deployments')
+		.select('id, status')
+		.eq('project_id', project_id)
+		.not('status', 'in', '("deployed","failed")')
+		.single();
+
+	if (existingDeployment) {
+		return {
+			result: {
+				success: false,
+				error: 'A deployment is already in progress',
+				existing_deployment_id: existingDeployment.id,
+				existing_status: existingDeployment.status,
+				hint: 'Wait for the current deployment to complete or cancel it first',
+			},
+		};
+	}
+
+	// Check for unvalidated completed tasks
+	const { data: unvalidatedTasks } = await supabase
+		.from('tasks')
+		.select('id, title, completed_at, completed_by_session_id')
+		.eq('project_id', project_id)
+		.eq('status', 'completed')
+		.is('validated_at', null)
+		.order('completed_at', { ascending: true });
+
+	if (unvalidatedTasks && unvalidatedTasks.length > 0) {
+		return {
+			result: {
+				success: false,
+				error: 'Cannot deploy: There are unvalidated completed tasks',
+				unvalidated_tasks: unvalidatedTasks.map(t => ({
+					id: t.id,
+					title: t.title,
+					completed_at: t.completed_at,
+				})),
+				unvalidated_count: unvalidatedTasks.length,
+				hint: 'All completed tasks must be validated before deployment. Use validate_task to review each task.',
+				action: `Call validate_task(task_id: "${unvalidatedTasks[0].id}", approved: true/false, validation_notes: "...")`,
+			},
+		};
+	}
+
+	// Get current version from project
+	const { data: project } = await supabase
+		.from('projects')
+		.select('current_version')
+		.eq('id', project_id)
+		.single();
+
+	const currentVersion = project?.current_version || '0.0.0';
+
+	// Create new deployment
+	const { data: deployment, error } = await supabase
+		.from('deployments')
+		.insert({
+			project_id,
+			environment,
+			version_bump,
+			notes,
+			git_ref,
+			requested_by: 'agent',
+			requesting_agent_session_id: currentSessionId,
+		})
+		.select()
+		.single();
+
+	if (error) throw error;
+
+	// Auto-convert pending deployment requirements to tasks
+	const { data: pendingRequirements } = await supabase
+		.from('deployment_requirements')
+		.select('id, type, title, description, stage, blocking')
+		.eq('project_id', project_id)
+		.eq('status', 'pending')
+		.is('converted_task_id', null);
+
+	const convertedTasks: Array<{ task_id: string; requirement_id: string; title: string }> = [];
+
+	if (pendingRequirements && pendingRequirements.length > 0) {
+		for (const req of pendingRequirements) {
+			const isDeployStage = req.stage === 'deployment';
+			const isBlocking = req.blocking ?? isDeployStage;
+			const titlePrefix = isBlocking
+				? 'DEPLOY:'
+				: isDeployStage
+					? 'DEPLOY:'
+					: req.stage === 'verification'
+						? 'VERIFY:'
+						: 'PREP:';
+
+			// Create linked task
+			const { data: newTask } = await supabase
+				.from('tasks')
+				.insert({
+					project_id,
+					title: `${titlePrefix} ${req.title}`,
+					description: `[${req.type}] ${req.description || req.title}`,
+					priority: 1,
+					status: 'pending',
+					blocking: isBlocking,
+					created_by: 'agent',
+					created_by_session_id: currentSessionId,
+				})
+				.select('id')
+				.single();
+
+			if (newTask) {
+				// Link task to requirement WITHOUT changing status
+				// This keeps the requirement visible in the deployment steps list (permanent)
+				await supabase
+					.from('deployment_requirements')
+					.update({
+						converted_task_id: newTask.id,
+					})
+					.eq('id', req.id);
+
+				convertedTasks.push({
+					task_id: newTask.id,
+					requirement_id: req.id,
+					title: `${titlePrefix} ${req.title}`,
+				});
+			}
+		}
+	}
+
+	// Log progress
+	const convertedMsg = convertedTasks.length > 0
+		? ` (${convertedTasks.length} requirements converted to tasks)`
+		: '';
+	await supabase.from('progress_logs').insert({
+		project_id,
+		summary: `Deployment requested for ${environment} (${version_bump} bump from ${currentVersion})${convertedMsg}`,
+		details: notes || undefined,
+		created_by: 'agent',
+		created_by_session_id: currentSessionId,
+	});
+
+	return {
+		result: {
+			success: true,
+			deployment_id: deployment.id,
+			status: deployment.status,
+			environment: deployment.environment,
+			version_bump,
+			current_version: currentVersion,
+			converted_requirements: convertedTasks.length,
+			converted_tasks: convertedTasks.length > 0 ? convertedTasks : undefined,
+			message: convertedTasks.length > 0
+				? `Deployment created. ${convertedTasks.length} requirements converted to tasks. Run build/tests then call claim_deployment_validation.`
+				: 'Deployment created. Run build/tests then call claim_deployment_validation.',
+		},
+	};
+};
+
+export const claimDeploymentValidation: Handler = async (args, ctx) => {
+	const { project_id } = args as { project_id: string };
+	const { supabase, session } = ctx;
+	const currentSessionId = session.currentSessionId;
+
+	validateRequired(project_id, 'project_id');
+	validateUUID(project_id, 'project_id');
+
+	// Find pending deployment
+	const { data: deployment, error: fetchError } = await supabase
+		.from('deployments')
+		.select('*')
+		.eq('project_id', project_id)
+		.eq('status', 'pending')
+		.single();
+
+	if (fetchError || !deployment) {
+		return {
+			result: {
+				success: false,
+				error: 'No pending deployment found',
+				hint: 'Use request_deployment to create a deployment first, or check_deployment_status to see current state',
+			},
+		};
+	}
+
+	// Claim validation
+	const { data: updated, error: updateError } = await supabase
+		.from('deployments')
+		.update({
+			status: 'validating',
+			validation_agent_session_id: currentSessionId,
+			validation_started_at: new Date().toISOString(),
+		})
+		.eq('id', deployment.id)
+		.eq('status', 'pending')
+		.select()
+		.single();
+
+	if (updateError || !updated) {
+		return {
+			result: {
+				success: false,
+				error: 'Failed to claim validation - deployment may have been claimed by another agent',
+			},
+		};
+	}
+
+	return {
+		result: {
+			success: true,
+			deployment_id: deployment.id,
+			status: 'validating',
+			message: 'Validation claimed. Run build and tests, then call report_validation with results.',
+		},
+	};
+};
+
+export const reportValidation: Handler = async (args, ctx) => {
+	const { project_id, build_passed, tests_passed, error_message } = args as {
+		project_id: string;
+		build_passed: boolean;
+		tests_passed?: boolean;
+		error_message?: string;
+	};
+
+	const { supabase, session } = ctx;
+	const currentSessionId = session.currentSessionId;
+
+	validateRequired(project_id, 'project_id');
+	validateUUID(project_id, 'project_id');
+	if (build_passed === undefined) {
+		throw new ValidationError('build_passed is required', {
+			field: 'build_passed',
+			hint: 'Set to true if the build succeeded, false otherwise',
+		});
+	}
+
+	// Find validating deployment
+	const { data: deployment, error: fetchError } = await supabase
+		.from('deployments')
+		.select('id')
+		.eq('project_id', project_id)
+		.eq('status', 'validating')
+		.single();
+
+	if (fetchError || !deployment) {
+		return {
+			result: {
+				success: false,
+				error: 'No deployment being validated. Use claim_deployment_validation first.',
+			},
+		};
+	}
+
+	const validationPassed = build_passed && (tests_passed !== false);
+	const newStatus = validationPassed ? 'ready' : 'failed';
+
+	const { error: updateError } = await supabase
+		.from('deployments')
+		.update({
+			status: newStatus,
+			build_passed,
+			tests_passed: tests_passed ?? null,
+			validation_completed_at: new Date().toISOString(),
+			validation_error: error_message || null,
+		})
+		.eq('id', deployment.id);
+
+	if (updateError) throw updateError;
+
+	// Log result
+	await supabase.from('progress_logs').insert({
+		project_id,
+		summary: validationPassed
+			? `Deployment validation passed - ready to deploy`
+			: `Deployment validation failed: ${error_message || 'build/tests failed'}`,
+		details: `Build: ${build_passed ? 'passed' : 'failed'}, Tests: ${tests_passed === undefined ? 'skipped' : tests_passed ? 'passed' : 'failed'}`,
+		created_by: 'agent',
+		created_by_session_id: currentSessionId,
+	});
+
+	// Auto-create task for failed validation
+	let createdTaskId: string | null = null;
+	if (!validationPassed) {
+		const failureType = !build_passed ? 'build' : 'test';
+		const { data: newTask } = await supabase
+			.from('tasks')
+			.insert({
+				project_id,
+				title: `Fix ${failureType} failure`,
+				description: error_message || `${failureType} failed during deployment validation`,
+				priority: 1,
+				status: 'pending',
+				created_by: 'agent',
+				created_by_session_id: currentSessionId,
+				estimated_minutes: 30,
+			})
+			.select('id')
+			.single();
+
+		createdTaskId = newTask?.id || null;
+	}
+
+	return {
+		result: {
+			success: true,
+			status: newStatus,
+			passed: validationPassed,
+			...(createdTaskId && { fix_task_id: createdTaskId }),
+		},
+	};
+};
+
+export const checkDeploymentStatus: Handler = async (args, ctx) => {
+	const { project_id } = args as { project_id: string };
+	const { supabase } = ctx;
+
+	validateRequired(project_id, 'project_id');
+	validateUUID(project_id, 'project_id');
+
+	// Get most recent deployment
+	const { data: deployment, error } = await supabase
+		.from('deployments')
+		.select('*')
+		.eq('project_id', project_id)
+		.order('created_at', { ascending: false })
+		.limit(1)
+		.single();
+
+	if (error || !deployment) {
+		return {
+			result: {
+				has_deployment: false,
+				message: 'No deployments found for this project',
+			},
+		};
+	}
+
+	// Auto-timeout stale deployments
+	const DEPLOYMENT_TIMEOUT_MS: Record<string, number> = {
+		pending: 30 * 60 * 1000,
+		validating: 15 * 60 * 1000,
+		ready: 30 * 60 * 1000,
+		deploying: 10 * 60 * 1000,
+	};
+
+	if (!['deployed', 'failed'].includes(deployment.status)) {
+		const timeout = DEPLOYMENT_TIMEOUT_MS[deployment.status];
+		if (timeout) {
+			const startTime =
+				deployment.status === 'deploying'
+					? deployment.deployment_started_at
+					: deployment.status === 'validating'
+						? deployment.validation_started_at
+						: deployment.created_at;
+
+			if (startTime && Date.now() - new Date(startTime).getTime() > timeout) {
+				const timeoutError = `Timed out: deployment was stuck in '${deployment.status}' state for too long`;
+				await supabase
+					.from('deployments')
+					.update({
+						status: 'failed',
+						deployment_error: timeoutError,
+						deployment_completed_at: new Date().toISOString(),
+					})
+					.eq('id', deployment.id);
+
+				deployment.status = 'failed';
+				deployment.deployment_error = timeoutError;
+			}
+		}
+	}
+
+	return {
+		result: {
+			has_deployment: true,
+			deployment: {
+				id: deployment.id,
+				status: deployment.status,
+				environment: deployment.environment,
+				requested_by: deployment.requested_by,
+				build_passed: deployment.build_passed,
+				tests_passed: deployment.tests_passed,
+				validation_error: deployment.validation_error,
+				deployment_error: deployment.deployment_error,
+				deployment_summary: deployment.deployment_summary,
+				notes: deployment.notes,
+				git_ref: deployment.git_ref,
+				created_at: deployment.created_at,
+				validation_started_at: deployment.validation_started_at,
+				validation_completed_at: deployment.validation_completed_at,
+				deployment_started_at: deployment.deployment_started_at,
+				deployment_completed_at: deployment.deployment_completed_at,
+			},
+		},
+	};
+};
+
+export const startDeployment: Handler = async (args, ctx) => {
+	const { project_id } = args as { project_id: string };
+	const { supabase, session } = ctx;
+	const currentSessionId = session.currentSessionId;
+
+	validateRequired(project_id, 'project_id');
+	validateUUID(project_id, 'project_id');
+
+	// Find ready deployment and project deployment instructions
+	const [deploymentResult, projectResult] = await Promise.all([
+		supabase
+			.from('deployments')
+			.select('id, environment')
+			.eq('project_id', project_id)
+			.eq('status', 'ready')
+			.single(),
+		supabase
+			.from('projects')
+			.select('deployment_instructions, git_main_branch')
+			.eq('id', project_id)
+			.single(),
+	]);
+
+	if (deploymentResult.error || !deploymentResult.data) {
+		return {
+			result: {
+				success: false,
+				error: 'No deployment ready. Must pass validation first.',
+			},
+		};
+	}
+
+	const deployment = deploymentResult.data;
+	const project = projectResult.data;
+
+	const { error: updateError } = await supabase
+		.from('deployments')
+		.update({
+			status: 'deploying',
+			deployment_started_at: new Date().toISOString(),
+		})
+		.eq('id', deployment.id);
+
+	if (updateError) throw updateError;
+
+	await supabase.from('progress_logs').insert({
+		project_id,
+		summary: `Deployment to ${deployment.environment} started`,
+		created_by: 'agent',
+		created_by_session_id: currentSessionId,
+	});
+
+	const result: Record<string, unknown> = {
+		success: true,
+		status: 'deploying',
+		env: deployment.environment,
+	};
+
+	if (project?.deployment_instructions) {
+		result.instructions = project.deployment_instructions;
+	} else {
+		result.instructions = `No deployment instructions configured. Common steps:\n1. Push to ${project?.git_main_branch || 'main'} branch\n2. Or run your deploy command (e.g., fly deploy, vercel deploy)\n3. Call complete_deployment when done`;
+	}
+
+	return { result };
+};
+
+export const completeDeployment: Handler = async (args, ctx) => {
+	const { project_id, success, summary } = args as {
+		project_id: string;
+		success: boolean;
+		summary?: string;
+	};
+
+	const { supabase, session } = ctx;
+	const currentSessionId = session.currentSessionId;
+
+	validateRequired(project_id, 'project_id');
+	validateUUID(project_id, 'project_id');
+	if (success === undefined) {
+		throw new ValidationError('success is required', {
+			field: 'success',
+			hint: 'Set to true if deployment succeeded, false otherwise',
+		});
+	}
+
+	// Find deploying deployment
+	const { data: deployment, error: fetchError } = await supabase
+		.from('deployments')
+		.select('id, environment, version_bump')
+		.eq('project_id', project_id)
+		.eq('status', 'deploying')
+		.single();
+
+	if (fetchError || !deployment) {
+		return {
+			result: {
+				success: false,
+				error: 'No deployment in progress. Use start_deployment first.',
+			},
+		};
+	}
+
+	const newStatus = success ? 'deployed' : 'failed';
+	let newVersion: string | null = null;
+
+	// If successful, calculate and store new version
+	if (success) {
+		const { data: project } = await supabase
+			.from('projects')
+			.select('current_version')
+			.eq('id', project_id)
+			.single();
+
+		const currentVersion = project?.current_version || '0.0.0';
+		const versionBump = deployment.version_bump || 'patch';
+		const parts = currentVersion.split('.').map((p: string) => parseInt(p, 10) || 0);
+		let [major, minor, patch] = [parts[0] || 0, parts[1] || 0, parts[2] || 0];
+
+		switch (versionBump) {
+			case 'major': major += 1; minor = 0; patch = 0; break;
+			case 'minor': minor += 1; patch = 0; break;
+			default: patch += 1;
+		}
+
+		newVersion = `${major}.${minor}.${patch}`;
+
+		await supabase
+			.from('projects')
+			.update({ current_version: newVersion })
+			.eq('id', project_id);
+	}
+
+	const { error: updateError } = await supabase
+		.from('deployments')
+		.update({
+			status: newStatus,
+			version: newVersion,
+			deployment_completed_at: new Date().toISOString(),
+			deployment_summary: summary || null,
+		})
+		.eq('id', deployment.id);
+
+	if (updateError) throw updateError;
+
+	await supabase.from('progress_logs').insert({
+		project_id,
+		summary: success
+			? `Deployed to ${deployment.environment}${newVersion ? ` v${newVersion}` : ''}`
+			: `Deployment failed`,
+		details: summary || undefined,
+		created_by: 'agent',
+		created_by_session_id: currentSessionId,
+	});
+
+	return {
+		result: {
+			success: true,
+			status: newStatus,
+			...(newVersion && { version: newVersion }),
+		},
+	};
+};
+
+export const cancelDeployment: Handler = async (args, ctx) => {
+	const { project_id, reason } = args as { project_id: string; reason?: string };
+	const { supabase, session } = ctx;
+	const currentSessionId = session.currentSessionId;
+
+	validateRequired(project_id, 'project_id');
+	validateUUID(project_id, 'project_id');
+
+	const { data: deployment, error: fetchError } = await supabase
+		.from('deployments')
+		.select('id')
+		.eq('project_id', project_id)
+		.not('status', 'in', '("deployed","failed")')
+		.single();
+
+	if (fetchError || !deployment) {
+		return { result: { success: false, error: 'No active deployment' } };
+	}
+
+	const { error: updateError } = await supabase
+		.from('deployments')
+		.update({
+			status: 'failed',
+			deployment_error: `Cancelled: ${reason || 'unspecified'}`,
+			deployment_completed_at: new Date().toISOString(),
+		})
+		.eq('id', deployment.id);
+
+	if (updateError) throw updateError;
+
+	await supabase.from('progress_logs').insert({
+		project_id,
+		summary: `Deployment cancelled${reason ? `: ${reason}` : ''}`,
+		created_by: 'agent',
+		created_by_session_id: currentSessionId,
+	});
+
+	return { result: { success: true } };
+};
+
+export const addDeploymentRequirement: Handler = async (args, ctx) => {
+	const { project_id, type, title, description, file_path, stage = 'preparation', blocking = false } = args as {
+		project_id: string;
+		type: string;
+		title: string;
+		description?: string;
+		file_path?: string;
+		stage?: string;
+		blocking?: boolean;
+	};
+
+	const { supabase, session } = ctx;
+	const currentSessionId = session.currentSessionId;
+
+	validateRequired(project_id, 'project_id');
+	validateUUID(project_id, 'project_id');
+	validateRequired(type, 'type');
+	validateRequired(title, 'title');
+
+	const validTypes = ['migration', 'env_var', 'config', 'manual', 'breaking_change', 'agent_task'];
+	if (!validTypes.includes(type)) {
+		throw new ValidationError(`type must be one of: ${validTypes.join(', ')}`);
+	}
+
+	const validStages = ['preparation', 'deployment', 'verification'];
+	if (!validStages.includes(stage)) {
+		throw new ValidationError(`stage must be one of: ${validStages.join(', ')}`);
+	}
+
+	const { data: requirement, error } = await supabase
+		.from('deployment_requirements')
+		.insert({
+			project_id,
+			type,
+			title,
+			description: description || null,
+			file_path: file_path || null,
+			stage,
+			blocking,
+			created_by_session_id: currentSessionId,
+		})
+		.select('id, type, title, stage, blocking')
+		.single();
+
+	if (error) throw new Error(`Failed to add requirement: ${error.message}`);
+
+	const blockingText = blocking ? ' (BLOCKING)' : '';
+	await supabase.from('progress_logs').insert({
+		project_id,
+		summary: `Added ${stage} deployment requirement${blockingText}: ${title}`,
+		details: `Type: ${type}, Stage: ${stage}${blocking ? ', Blocking: true' : ''}${file_path ? `, File: ${file_path}` : ''}`,
+		created_by: 'agent',
+		created_by_session_id: currentSessionId,
+	});
+
+	const stageMessage = blocking
+		? 'Will block all other work when converted to task.'
+		: stage === 'deployment'
+			? 'Will run during deployment.'
+			: stage === 'verification'
+				? 'Will run after deployment for verification.'
+				: 'Will run during preparation phase.';
+
+	return {
+		result: {
+			success: true,
+			requirement_id: requirement.id,
+			stage: requirement.stage,
+			message: `Added ${type} requirement. ${stageMessage}`,
+		},
+	};
+};
+
+export const completeDeploymentRequirement: Handler = async (args, ctx) => {
+	const { requirement_id } = args as { requirement_id: string };
+	const { supabase, session } = ctx;
+	const currentSessionId = session.currentSessionId;
+
+	validateRequired(requirement_id, 'requirement_id');
+	validateUUID(requirement_id, 'requirement_id');
+
+	const { data: requirement, error: fetchError } = await supabase
+		.from('deployment_requirements')
+		.select('id, title, status')
+		.eq('id', requirement_id)
+		.single();
+
+	if (fetchError || !requirement) {
+		throw new Error('Requirement not found');
+	}
+
+	if (requirement.status !== 'pending') {
+		return {
+			result: {
+				success: false,
+				error: `Requirement is already ${requirement.status}`,
+			},
+		};
+	}
+
+	const { error: updateError } = await supabase
+		.from('deployment_requirements')
+		.update({
+			status: 'completed',
+			completed_at: new Date().toISOString(),
+			completed_by: currentSessionId || 'agent',
+		})
+		.eq('id', requirement_id);
+
+	if (updateError) throw updateError;
+
+	return {
+		result: {
+			success: true,
+			requirement_id,
+			title: requirement.title,
+		},
+	};
+};
+
+export const getDeploymentRequirements: Handler = async (args, ctx) => {
+	const { project_id, status = 'pending', stage } = args as {
+		project_id: string;
+		status?: string;
+		stage?: string;
+	};
+
+	const { supabase } = ctx;
+
+	validateRequired(project_id, 'project_id');
+	validateUUID(project_id, 'project_id');
+
+	let query = supabase
+		.from('deployment_requirements')
+		.select('id, type, title, description, file_path, status, stage, blocking, created_at, completed_at')
+		.eq('project_id', project_id)
+		.order('stage', { ascending: true })
+		.order('created_at', { ascending: false });
+
+	if (status !== 'all') {
+		query = query.eq('status', status);
+	}
+
+	if (stage && stage !== 'all') {
+		query = query.eq('stage', stage);
+	}
+
+	const { data: requirements, error } = await query;
+
+	if (error) throw new Error(`Failed to fetch requirements: ${error.message}`);
+
+	const preparationPending = requirements?.filter(r => r.status === 'pending' && r.stage === 'preparation').length || 0;
+	const deploymentPending = requirements?.filter(r => r.status === 'pending' && r.stage === 'deployment').length || 0;
+
+	return {
+		result: {
+			requirements: requirements || [],
+			preparation_pending: preparationPending,
+			deployment_pending: deploymentPending,
+			deployment_blocked: preparationPending > 0 || deploymentPending > 0,
+		},
+	};
+};
+
+// ============================================================================
+// Scheduled Deployments
+// ============================================================================
+
+export const scheduleDeployment: Handler = async (args, ctx) => {
+	const {
+		project_id,
+		environment = 'production',
+		version_bump = 'patch',
+		schedule_type = 'once',
+		scheduled_at,
+		auto_trigger = true,
+		notes,
+		git_ref,
+	} = args as {
+		project_id: string;
+		environment?: string;
+		version_bump?: string;
+		schedule_type?: string;
+		scheduled_at: string;
+		auto_trigger?: boolean;
+		notes?: string;
+		git_ref?: string;
+	};
+
+	const { supabase, session } = ctx;
+	const currentSessionId = session.currentSessionId;
+
+	validateRequired(project_id, 'project_id');
+	validateUUID(project_id, 'project_id');
+	validateRequired(scheduled_at, 'scheduled_at');
+	validateEnvironment(environment);
+
+	if (!['patch', 'minor', 'major'].includes(version_bump)) {
+		throw new ValidationError('Invalid version_bump value', {
+			field: 'version_bump',
+			validValues: ['patch', 'minor', 'major'],
+		});
+	}
+
+	if (!['once', 'daily', 'weekly', 'monthly'].includes(schedule_type)) {
+		throw new ValidationError('Invalid schedule_type value', {
+			field: 'schedule_type',
+			validValues: ['once', 'daily', 'weekly', 'monthly'],
+		});
+	}
+
+	// Parse and validate scheduled_at
+	const scheduledDate = new Date(scheduled_at);
+	if (isNaN(scheduledDate.getTime())) {
+		throw new ValidationError('Invalid scheduled_at date format', {
+			field: 'scheduled_at',
+			hint: 'Use ISO 8601 format, e.g., 2025-01-15T14:00:00Z',
+		});
+	}
+
+	if (scheduledDate.getTime() <= Date.now()) {
+		throw new ValidationError('scheduled_at must be in the future', {
+			field: 'scheduled_at',
+		});
+	}
+
+	// Create scheduled deployment
+	const { data: schedule, error } = await supabase
+		.from('scheduled_deployments')
+		.insert({
+			project_id,
+			environment,
+			version_bump,
+			schedule_type,
+			scheduled_at: scheduledDate.toISOString(),
+			auto_trigger,
+			notes: notes || null,
+			git_ref: git_ref || null,
+			created_by: 'agent',
+			created_by_session_id: currentSessionId,
+		})
+		.select('id, scheduled_at, schedule_type')
+		.single();
+
+	if (error) throw new Error(`Failed to create schedule: ${error.message}`);
+
+	// Log progress
+	await supabase.from('progress_logs').insert({
+		project_id,
+		summary: `Scheduled ${schedule_type} deployment to ${environment} for ${scheduledDate.toISOString()}`,
+		details: `Auto-trigger: ${auto_trigger}, Version bump: ${version_bump}`,
+		created_by: 'agent',
+		created_by_session_id: currentSessionId,
+	});
+
+	return {
+		result: {
+			success: true,
+			schedule_id: schedule.id,
+			scheduled_at: schedule.scheduled_at,
+			schedule_type: schedule.schedule_type,
+			auto_trigger,
+			message: auto_trigger
+				? 'Deployment scheduled. Will trigger automatically when time arrives.'
+				: 'Deployment scheduled. Manual trigger required from dashboard.',
+		},
+	};
+};
+
+export const getScheduledDeployments: Handler = async (args, ctx) => {
+	const { project_id, include_disabled = false } = args as {
+		project_id: string;
+		include_disabled?: boolean;
+	};
+
+	const { supabase } = ctx;
+
+	validateRequired(project_id, 'project_id');
+	validateUUID(project_id, 'project_id');
+
+	let query = supabase
+		.from('scheduled_deployments')
+		.select('*')
+		.eq('project_id', project_id)
+		.order('scheduled_at', { ascending: true });
+
+	if (!include_disabled) {
+		query = query.eq('enabled', true);
+	}
+
+	const { data: schedules, error } = await query;
+
+	if (error) throw new Error(`Failed to fetch schedules: ${error.message}`);
+
+	const now = new Date();
+	const schedulesWithStatus = (schedules || []).map(s => ({
+		...s,
+		is_due: s.enabled && new Date(s.scheduled_at) <= now,
+	}));
+
+	const dueCount = schedulesWithStatus.filter(s => s.is_due && s.auto_trigger).length;
+
+	return {
+		result: {
+			schedules: schedulesWithStatus,
+			count: schedulesWithStatus.length,
+			due_count: dueCount,
+			...(dueCount > 0 && {
+				hint: 'There are due schedules. Call trigger_scheduled_deployment to execute.',
+			}),
+		},
+	};
+};
+
+export const updateScheduledDeployment: Handler = async (args, ctx) => {
+	const {
+		schedule_id,
+		environment,
+		version_bump,
+		schedule_type,
+		scheduled_at,
+		auto_trigger,
+		enabled,
+		notes,
+		git_ref,
+	} = args as {
+		schedule_id: string;
+		environment?: string;
+		version_bump?: string;
+		schedule_type?: string;
+		scheduled_at?: string;
+		auto_trigger?: boolean;
+		enabled?: boolean;
+		notes?: string;
+		git_ref?: string;
+	};
+
+	const { supabase } = ctx;
+
+	validateRequired(schedule_id, 'schedule_id');
+	validateUUID(schedule_id, 'schedule_id');
+
+	const updates: Record<string, unknown> = {};
+
+	if (environment !== undefined) {
+		validateEnvironment(environment);
+		updates.environment = environment;
+	}
+
+	if (version_bump !== undefined) {
+		if (!['patch', 'minor', 'major'].includes(version_bump)) {
+			throw new ValidationError('Invalid version_bump value');
+		}
+		updates.version_bump = version_bump;
+	}
+
+	if (schedule_type !== undefined) {
+		if (!['once', 'daily', 'weekly', 'monthly'].includes(schedule_type)) {
+			throw new ValidationError('Invalid schedule_type value');
+		}
+		updates.schedule_type = schedule_type;
+	}
+
+	if (scheduled_at !== undefined) {
+		const scheduledDate = new Date(scheduled_at);
+		if (isNaN(scheduledDate.getTime())) {
+			throw new ValidationError('Invalid scheduled_at date format');
+		}
+		updates.scheduled_at = scheduledDate.toISOString();
+	}
+
+	if (auto_trigger !== undefined) updates.auto_trigger = auto_trigger;
+	if (enabled !== undefined) updates.enabled = enabled;
+	if (notes !== undefined) updates.notes = notes;
+	if (git_ref !== undefined) updates.git_ref = git_ref;
+
+	if (Object.keys(updates).length === 0) {
+		return { result: { success: false, error: 'No updates provided' } };
+	}
+
+	const { error } = await supabase
+		.from('scheduled_deployments')
+		.update(updates)
+		.eq('id', schedule_id);
+
+	if (error) throw new Error(`Failed to update schedule: ${error.message}`);
+
+	return { result: { success: true, schedule_id } };
+};
+
+export const deleteScheduledDeployment: Handler = async (args, ctx) => {
+	const { schedule_id } = args as { schedule_id: string };
+	const { supabase } = ctx;
+
+	validateRequired(schedule_id, 'schedule_id');
+	validateUUID(schedule_id, 'schedule_id');
+
+	const { error } = await supabase
+		.from('scheduled_deployments')
+		.delete()
+		.eq('id', schedule_id);
+
+	if (error) throw new Error(`Failed to delete schedule: ${error.message}`);
+
+	return { result: { success: true } };
+};
+
+export const triggerScheduledDeployment: Handler = async (args, ctx) => {
+	const { schedule_id } = args as { schedule_id: string };
+	const { supabase, session } = ctx;
+	const currentSessionId = session.currentSessionId;
+
+	validateRequired(schedule_id, 'schedule_id');
+	validateUUID(schedule_id, 'schedule_id');
+
+	// Get the schedule
+	const { data: schedule, error: fetchError } = await supabase
+		.from('scheduled_deployments')
+		.select('*')
+		.eq('id', schedule_id)
+		.single();
+
+	if (fetchError || !schedule) {
+		return { result: { success: false, error: 'Schedule not found' } };
+	}
+
+	if (!schedule.enabled) {
+		return { result: { success: false, error: 'Schedule is disabled' } };
+	}
+
+	// Check for existing active deployment
+	const { data: existingDeployment } = await supabase
+		.from('deployments')
+		.select('id, status')
+		.eq('project_id', schedule.project_id)
+		.not('status', 'in', '("deployed","failed")')
+		.single();
+
+	if (existingDeployment) {
+		return {
+			result: {
+				success: false,
+				error: 'A deployment is already in progress',
+				existing_deployment_id: existingDeployment.id,
+				hint: 'Wait for current deployment to complete or cancel it first',
+			},
+		};
+	}
+
+	// Create the deployment (similar to request_deployment)
+	const { data: deployment, error: deployError } = await supabase
+		.from('deployments')
+		.insert({
+			project_id: schedule.project_id,
+			environment: schedule.environment,
+			version_bump: schedule.version_bump,
+			notes: schedule.notes,
+			git_ref: schedule.git_ref,
+			requested_by: 'agent',
+			requesting_agent_session_id: currentSessionId,
+		})
+		.select('id, status')
+		.single();
+
+	if (deployError) throw new Error(`Failed to create deployment: ${deployError.message}`);
+
+	// Auto-convert pending deployment requirements to tasks
+	const { data: pendingRequirements } = await supabase
+		.from('deployment_requirements')
+		.select('id, type, title, description, stage, blocking')
+		.eq('project_id', schedule.project_id)
+		.eq('status', 'pending')
+		.is('converted_task_id', null);
+
+	const convertedTasks: Array<{ task_id: string; requirement_id: string; title: string }> = [];
+
+	if (pendingRequirements && pendingRequirements.length > 0) {
+		for (const req of pendingRequirements) {
+			const isDeployStage = req.stage === 'deployment';
+			const isBlocking = req.blocking ?? isDeployStage;
+			const titlePrefix = isBlocking
+				? 'DEPLOY:'
+				: isDeployStage
+					? 'DEPLOY:'
+					: req.stage === 'verification'
+						? 'VERIFY:'
+						: 'PREP:';
+
+			// Create linked task
+			const { data: newTask } = await supabase
+				.from('tasks')
+				.insert({
+					project_id: schedule.project_id,
+					title: `${titlePrefix} ${req.title}`,
+					description: `[${req.type}] ${req.description || req.title}`,
+					priority: 1,
+					status: 'pending',
+					blocking: isBlocking,
+					created_by: 'agent',
+					created_by_session_id: currentSessionId,
+				})
+				.select('id')
+				.single();
+
+			if (newTask) {
+				// Link task to requirement WITHOUT changing status
+				// This keeps the requirement visible in the deployment steps list (permanent)
+				await supabase
+					.from('deployment_requirements')
+					.update({
+						converted_task_id: newTask.id,
+					})
+					.eq('id', req.id);
+
+				convertedTasks.push({
+					task_id: newTask.id,
+					requirement_id: req.id,
+					title: `${titlePrefix} ${req.title}`,
+				});
+			}
+		}
+	}
+
+	// Update the schedule
+	const scheduleUpdates: Record<string, unknown> = {
+		last_triggered_at: new Date().toISOString(),
+		last_deployment_id: deployment.id,
+		trigger_count: schedule.trigger_count + 1,
+	};
+
+	// For recurring schedules, calculate next run time
+	if (schedule.schedule_type !== 'once') {
+		const currentScheduledAt = new Date(schedule.scheduled_at);
+		let nextScheduledAt: Date;
+
+		switch (schedule.schedule_type) {
+			case 'daily':
+				nextScheduledAt = new Date(currentScheduledAt.getTime() + 24 * 60 * 60 * 1000);
+				break;
+			case 'weekly':
+				nextScheduledAt = new Date(currentScheduledAt.getTime() + 7 * 24 * 60 * 60 * 1000);
+				break;
+			case 'monthly':
+				nextScheduledAt = new Date(currentScheduledAt.getTime() + 30 * 24 * 60 * 60 * 1000);
+				break;
+			default:
+				nextScheduledAt = currentScheduledAt;
+		}
+
+		scheduleUpdates.scheduled_at = nextScheduledAt.toISOString();
+	} else {
+		// One-time schedule, disable it
+		scheduleUpdates.enabled = false;
+	}
+
+	await supabase
+		.from('scheduled_deployments')
+		.update(scheduleUpdates)
+		.eq('id', schedule_id);
+
+	// Log progress
+	const convertedMsg = convertedTasks.length > 0
+		? `, ${convertedTasks.length} requirements converted to tasks`
+		: '';
+	await supabase.from('progress_logs').insert({
+		project_id: schedule.project_id,
+		summary: `Triggered scheduled deployment to ${schedule.environment}${convertedMsg}`,
+		details: `Schedule: ${schedule.schedule_type}, Trigger #${schedule.trigger_count + 1}`,
+		created_by: 'agent',
+		created_by_session_id: currentSessionId,
+	});
+
+	return {
+		result: {
+			success: true,
+			deployment_id: deployment.id,
+			schedule_id,
+			schedule_type: schedule.schedule_type,
+			next_scheduled_at: schedule.schedule_type !== 'once' ? scheduleUpdates.scheduled_at : null,
+			converted_requirements: convertedTasks.length,
+			converted_tasks: convertedTasks.length > 0 ? convertedTasks : undefined,
+			message: convertedTasks.length > 0
+				? `Deployment created from schedule. ${convertedTasks.length} requirements converted to tasks. Run validation then deploy.`
+				: 'Deployment created from schedule. Run validation then deploy.',
+		},
+	};
+};
+
+export const checkDueDeployments: Handler = async (args, ctx) => {
+	const { project_id } = args as { project_id: string };
+	const { supabase } = ctx;
+
+	validateRequired(project_id, 'project_id');
+	validateUUID(project_id, 'project_id');
+
+	// Find schedules that are due (enabled, auto_trigger, and scheduled_at <= now)
+	const { data: dueSchedules, error } = await supabase
+		.from('scheduled_deployments')
+		.select('id, environment, version_bump, schedule_type, scheduled_at')
+		.eq('project_id', project_id)
+		.eq('enabled', true)
+		.eq('auto_trigger', true)
+		.lte('scheduled_at', new Date().toISOString())
+		.order('scheduled_at', { ascending: true });
+
+	if (error) throw new Error(`Failed to check schedules: ${error.message}`);
+
+	return {
+		result: {
+			due_schedules: dueSchedules || [],
+			count: dueSchedules?.length || 0,
+			...(dueSchedules && dueSchedules.length > 0 && {
+				hint: `Call trigger_scheduled_deployment(schedule_id: "${dueSchedules[0].id}") to trigger the first due deployment`,
+			}),
+		},
+	};
+};
+
+/**
+ * Deployment handlers registry
+ */
+export const deploymentHandlers: HandlerRegistry = {
+	request_deployment: requestDeployment,
+	claim_deployment_validation: claimDeploymentValidation,
+	report_validation: reportValidation,
+	check_deployment_status: checkDeploymentStatus,
+	start_deployment: startDeployment,
+	complete_deployment: completeDeployment,
+	cancel_deployment: cancelDeployment,
+	add_deployment_requirement: addDeploymentRequirement,
+	complete_deployment_requirement: completeDeploymentRequirement,
+	get_deployment_requirements: getDeploymentRequirements,
+	// Scheduled deployments
+	schedule_deployment: scheduleDeployment,
+	get_scheduled_deployments: getScheduledDeployments,
+	update_scheduled_deployment: updateScheduledDeployment,
+	delete_scheduled_deployment: deleteScheduledDeployment,
+	trigger_scheduled_deployment: triggerScheduledDeployment,
+	check_due_deployments: checkDueDeployments,
+};