@vibescope/mcp-server 0.0.1 → 0.2.0

package/src/handlers/session.ts

@@ -9,76 +9,8 @@
  * - get_token_usage
  */
 
-import type { SupabaseClient } from '@supabase/supabase-js';
-import type { Handler, HandlerRegistry, AuthContext, TokenUsage, UserUpdates } from './types.js';
-import { selectPersona, extractProjectNameFromGitUrl } from '../utils.js';
-import { KNOWLEDGE_BASE } from '../knowledge.js';
-
-/**
- * Get user-created items since last sync
- */
-async function getUserUpdates(
-	supabase: SupabaseClient,
-	auth: AuthContext,
-	projectId: string,
-	currentSessionId: string | null
-): Promise<UserUpdates | undefined> {
-	let lastSyncedAt: string;
-
-	if (currentSessionId) {
-		const { data: session } = await supabase
-			.from('agent_sessions')
-			.select('last_synced_at')
-			.eq('id', currentSessionId)
-			.single();
-		lastSyncedAt = session?.last_synced_at || new Date(0).toISOString();
-	} else {
-		const { data: session } = await supabase
-			.from('agent_sessions')
-			.select('last_synced_at')
-			.eq('api_key_id', auth.apiKeyId)
-			.eq('project_id', projectId)
-			.single();
-		lastSyncedAt = session?.last_synced_at || new Date(0).toISOString();
-	}
-
-	const [tasksResult, blockersResult, ideasResult] = await Promise.all([
-		supabase
-			.from('tasks')
-			.select('id, title, created_at')
-			.eq('project_id', projectId)
-			.eq('created_by', 'user')
-			.gt('created_at', lastSyncedAt)
-			.order('created_at', { ascending: false })
-			.limit(5),
-		supabase
-			.from('blockers')
-			.select('id, description, created_at')
-			.eq('project_id', projectId)
-			.eq('created_by', 'user')
-			.gt('created_at', lastSyncedAt)
-			.order('created_at', { ascending: false })
-			.limit(5),
-		supabase
-			.from('ideas')
-			.select('id, title, created_at')
-			.eq('project_id', projectId)
-			.eq('created_by', 'user')
-			.gt('created_at', lastSyncedAt)
-			.order('created_at', { ascending: false })
-			.limit(5),
-	]);
-
-	const tasks = tasksResult.data || [];
-	const blockers = blockersResult.data || [];
-	const ideas = ideasResult.data || [];
-
-	if (tasks.length === 0 && blockers.length === 0 && ideas.length === 0) {
-		return undefined;
-	}
-
-	return { tasks, blockers, ideas };
-}
+import type { Handler, HandlerRegistry, TokenUsage } from './types.js';
+import { getApiClient } from '../api-client.js';
 
 export const startWorkSession: Handler = async (args, ctx) => {
 	const { project_id, git_url, mode = 'lite', model, role = 'developer' } = args as {
@@ -89,8 +21,7 @@ export const startWorkSession: Handler = async (args, ctx) => {
 		role?: 'developer' | 'validator' | 'deployer' | 'reviewer' | 'maintainer';
 	};
 
-	const { supabase, auth, session, updateSession } = ctx;
-	const INSTANCE_ID = session.instanceId;
+	const { session, updateSession } = ctx;
 
 	// Reset token tracking for new session with model info
 	const normalizedModel = model ? model.toLowerCase().replace(/^claude[- ]*/i, '') : null;
@@ -108,8 +39,6 @@ export const startWorkSession: Handler = async (args, ctx) => {
 		},
 	});
 
-	const isLiteMode = mode === 'lite';
-
 	// Require project_id or git_url
 	if (!project_id && !git_url) {
 		return {
@@ -119,528 +48,102 @@ export const startWorkSession: Handler = async (args, ctx) => {
 		};
 	}
 
-	// Find project - try owned projects first, then shared projects for org-scoped keys
-	let project: {
-		id: string;
-		name: string;
-		description: string | null;
-		goal: string | null;
-		status: string;
-		git_url: string | null;
-		agent_instructions: string | null;
-		tech_stack: string[] | null;
-	} | null = null;
-
-	// First try: user-owned projects
-	let query = supabase
-		.from('projects')
-		.select('id, name, description, goal, status, git_url, agent_instructions, tech_stack')
-		.eq('user_id', auth.userId);
-
-	if (project_id) {
-		query = query.eq('id', project_id);
-	} else if (git_url) {
-		query = query.eq('git_url', git_url);
-	}
-
-	const { data: ownedProject } = await query.single();
-	project = ownedProject;
-
-	// Second try: if org-scoped key and no owned project found, check shared projects
-	if (!project && auth.scope === 'organization' && auth.organizationId) {
-		// Get project IDs shared with this organization
-		const { data: shares } = await supabase
-			.from('project_shares')
-			.select('project_id')
-			.eq('organization_id', auth.organizationId);
-
-		if (shares && shares.length > 0) {
-			const sharedProjectIds = shares.map((s) => s.project_id);
-
-			let sharedQuery = supabase
-				.from('projects')
-				.select('id, name, description, goal, status, git_url, agent_instructions, tech_stack')
-				.in('id', sharedProjectIds);
-
-			if (project_id) {
-				sharedQuery = sharedQuery.eq('id', project_id);
-			} else if (git_url) {
-				sharedQuery = sharedQuery.eq('git_url', git_url);
-			}
-
-			const { data: sharedProject } = await sharedQuery.single();
-			project = sharedProject;
-		}
-	}
-
-	if (!project) {
-		const suggestedName = extractProjectNameFromGitUrl(git_url || '');
+	const apiClient = getApiClient();
+	const response = await apiClient.startSession({
+		project_id,
+		git_url,
+		mode,
+		model,
+		role
+	});
 
+	if (!response.ok) {
 		return {
 			result: {
-				session_started: false,
-				project_not_found: true,
-				message: `No project found for this repository. Would you like to create one?`,
-				suggestion: {
-					action: 'create_project',
-					example: `create_project(name: "${suggestedName}", git_url: "${git_url || ''}", description: "Brief description of your project", goal: "What does done look like?")`,
-					note: 'After creating the project, call start_work_session again to begin working.',
-				},
+				error: response.error || 'Failed to start session',
 			},
 		};
 	}
 
-	// Create or update agent session with instance tracking
-	const { data: existingSession } = await supabase
-		.from('agent_sessions')
-		.select('id, agent_name')
-		.eq('api_key_id', auth.apiKeyId)
-		.eq('project_id', project.id)
-		.eq('instance_id', INSTANCE_ID)
-		.single();
-
-	let sessionId!: string;
-	let assignedPersona!: string;
-
-	if (existingSession && existingSession.agent_name) {
-		// Reuse existing persona for this instance
-		assignedPersona = existingSession.agent_name;
-		await supabase
-			.from('agent_sessions')
-			.update({
-				last_synced_at: new Date().toISOString(),
-				status: 'active',
-			})
-			.eq('id', existingSession.id);
-		sessionId = existingSession.id;
-	} else {
-		// Find which personas are currently in use by active sessions
-		const { data: activeSessions } = await supabase
-			.from('agent_sessions')
-			.select('agent_name')
-			.eq('project_id', project.id)
-			.neq('status', 'disconnected')
-			.gte('last_synced_at', new Date(Date.now() - 5 * 60 * 1000).toISOString());
-
-		const usedPersonas = new Set(
-			(activeSessions || [])
-				.map((s) => s.agent_name)
-				.filter((name): name is string => !!name)
-		);
-
-		// Retry loop for persona assignment
-		const MAX_PERSONA_RETRIES = 5;
-		let personaAssigned = false;
-
-		for (let attempt = 0; attempt < MAX_PERSONA_RETRIES && !personaAssigned; attempt++) {
-			assignedPersona = selectPersona(usedPersonas, INSTANCE_ID);
-
-			if (existingSession) {
-				const { error: updateError } = await supabase
-					.from('agent_sessions')
-					.update({
-						last_synced_at: new Date().toISOString(),
-						agent_name: assignedPersona,
-						status: 'active',
-					})
-					.eq('id', existingSession.id);
-
-				if (updateError?.code === '23505') {
-					usedPersonas.add(assignedPersona);
-					continue;
-				}
-				sessionId = existingSession.id;
-				personaAssigned = true;
-			} else {
-				const { data: newSession, error: sessionError } = await supabase
-					.from('agent_sessions')
-					.insert({
-						api_key_id: auth.apiKeyId,
-						project_id: project.id,
-						instance_id: INSTANCE_ID,
-						last_synced_at: new Date().toISOString(),
-						agent_name: assignedPersona,
-						status: 'active',
-					})
-					.select('id')
-					.single();
-
-				if (sessionError?.code === '23505') {
-					usedPersonas.add(assignedPersona);
-					continue;
-				}
-
-				if (sessionError || !newSession) {
-					throw new Error(`Failed to create agent session: ${sessionError?.message}`);
-				}
-				sessionId = newSession.id;
-				personaAssigned = true;
-			}
-		}
+	const data = response.data;
 
-		// Fallback if all retries failed
-		if (!personaAssigned) {
-			assignedPersona = `Agent-${INSTANCE_ID.slice(0, 6)}`;
-			if (existingSession) {
-				await supabase
-					.from('agent_sessions')
-					.update({
-						last_synced_at: new Date().toISOString(),
-						agent_name: assignedPersona,
-						status: 'active',
-					})
-					.eq('id', existingSession.id);
-				sessionId = existingSession.id;
-			} else {
-				const { data: newSession, error: sessionError } = await supabase
-					.from('agent_sessions')
-					.insert({
-						api_key_id: auth.apiKeyId,
-						project_id: project.id,
-						instance_id: INSTANCE_ID,
-						last_synced_at: new Date().toISOString(),
-						agent_name: assignedPersona,
-						status: 'active',
-					})
-					.select('id')
-					.single();
-
-				if (sessionError || !newSession) {
-					throw new Error(`Failed to create agent session: ${sessionError?.message}`);
-				}
-				sessionId = newSession.id;
-			}
-		}
+	// Handle project not found
+	if (!data?.session_started) {
+		return { result: data };
 	}
 
-	// Store session ID and persona
-	updateSession({
-		currentSessionId: sessionId,
-		currentPersona: assignedPersona,
-	});
-
-	// Log session start
-	await supabase.from('progress_logs').insert({
-		project_id: project.id,
-		summary: `Agent session started (${assignedPersona}) [${INSTANCE_ID.slice(0, 8)}]`,
-		created_by: 'agent',
-		created_by_session_id: sessionId,
-	});
-
-	// Insert initial heartbeat
-	await supabase.from('agent_heartbeats').insert({
-		session_id: sessionId,
-	});
-
-	// LITE MODE: Minimal fetches
-	if (isLiteMode) {
-		const [nextTaskResult, blockersCountResult, validationCountResult, deploymentResult, requestsResult, firstQuestionResult] =
-			await Promise.all([
-				supabase
-					.from('tasks')
-					.select('id, title, priority, estimated_minutes')
-					.eq('project_id', project.id)
-					.eq('status', 'pending')
-					.is('working_agent_session_id', null)
-					.order('priority', { ascending: true })
-					.order('created_at', { ascending: true })
-					.limit(1)
-					.maybeSingle(),
-				supabase
-					.from('blockers')
-					.select('id', { count: 'exact', head: true })
-					.eq('project_id', project.id)
-					.eq('status', 'open'),
-				supabase
-					.from('tasks')
-					.select('id', { count: 'exact', head: true })
-					.eq('project_id', project.id)
-					.eq('status', 'completed')
-					.is('validated_at', null),
-				supabase
-					.from('deployments')
-					.select('id, status, environment')
-					.eq('project_id', project.id)
-					.not('status', 'in', '("deployed","failed")')
-					.limit(1)
-					.maybeSingle(),
-				supabase
-					.from('agent_requests')
-					.select('id', { count: 'exact', head: true })
-					.eq('project_id', project.id)
-					.is('acknowledged_at', null),
-				// Fetch first unanswered question with details (not just count)
-				supabase
-					.from('agent_requests')
-					.select('id, message, created_at')
-					.eq('project_id', project.id)
-					.eq('request_type', 'question')
-					.is('answered_at', null)
-					.order('created_at', { ascending: true })
-					.limit(1)
-					.maybeSingle(),
-			]);
-
-		const blockersCount = blockersCountResult.count || 0;
-		const validationCount = validationCountResult.count || 0;
-		const requestsCount = requestsResult.count || 0;
-		const firstQuestion = firstQuestionResult.data;
-
-		// Determine directive and next action FIRST
-		let directive: string;
-		let nextAction: string;
-
-		if (firstQuestion) {
-			directive = 'ACTION_REQUIRED: Answer this question immediately. Do NOT ask for permission.';
-			nextAction = `answer_question(request_id: "${firstQuestion.id}", answer: "...")`;
-		} else if (nextTaskResult.data) {
-			directive = 'ACTION_REQUIRED: Start this task immediately. Do NOT ask for permission or confirmation.';
-			nextAction = `update_task(task_id: "${nextTaskResult.data.id}", status: "in_progress")`;
-		} else {
-			directive = 'ACTION_REQUIRED: No pending tasks. Start a fallback activity NOW without asking.';
-			nextAction = 'start_fallback_activity(project_id: "...", activity: "code_review")';
-		}
-
-		// Build result with directive at TOP for visibility
-		const result: Record<string, unknown> = {
-			session_started: true,
-			directive, // FIRST - most important signal
-			auto_continue: true, // Explicit flag for autonomous operation
-			session_id: sessionId,
-			persona: assignedPersona,
-			project: { id: project.id, name: project.name, goal: project.goal },
-		};
-
-		// Add task or question details
-		if (firstQuestion) {
-			const now = new Date();
-			const waitMinutes = Math.floor((now.getTime() - new Date(firstQuestion.created_at).getTime()) / 60000);
-			result.first_question = {
-				id: firstQuestion.id,
-				message: firstQuestion.message,
-				wait_minutes: waitMinutes,
-			};
-			result.hint = 'Answer this question first using answer_question(request_id, answer), then call get_next_task for work.';
-		} else {
-			result.next_task = nextTaskResult.data;
-		}
-
-		if (blockersCount > 0) result.blockers_count = blockersCount;
-		if (validationCount > 0) result.validation_count = validationCount;
-		if (requestsCount > 0) result.requests_count = requestsCount;
-
-		if (deploymentResult.data) {
-			const actions: Record<string, string> = {
-				pending: 'claim_deployment_validation',
-				validating: 'wait',
-				ready: 'start_deployment',
-				deploying: 'wait',
-			};
-			result.deployment_priority = {
-				id: deploymentResult.data.id,
-				status: deploymentResult.data.status,
-				action: actions[deploymentResult.data.status] || 'check_deployment_status',
-			};
-		}
-
-		result.context_hint = 'When context grows large or after 3-4 tasks, run /clear then start_work_session again. Do not ask permission to clear context.';
-
-		// Add model tracking info
-		if (validModel) {
-			result.model_tracking = { model: validModel, status: 'active' };
-		} else {
-			result.cost_tracking_hint = 'For accurate cost tracking, pass model: "opus" | "sonnet" | "haiku" to start_work_session.';
-		}
-
-		// REPEAT at end - agents weight last items heavily
-		result.next_action = nextAction;
-
-		return { result };
+	// Store session ID and persona in local state
+	if (data.session_id) {
+		updateSession({
+			currentSessionId: data.session_id,
+			currentPersona: data.persona || null,
+		});
 	}
 
-	// FULL MODE: Complete context
-	const [tasksResult, blockersResult, decisionsResult, progressResult, ideasResult, requestsResult, deploymentResult, findingsResult] =
-		await Promise.all([
-			supabase
-				.from('tasks')
-				.select('id, title, description, priority, status, estimated_minutes')
-				.eq('project_id', project.id)
-				.in('status', ['pending', 'in_progress'])
-				.order('priority', { ascending: true })
-				.limit(10),
-			supabase
-				.from('blockers')
-				.select('id, description')
-				.eq('project_id', project.id)
-				.eq('status', 'open')
-				.limit(5),
-			supabase
-				.from('decisions')
-				.select('title')
-				.eq('project_id', project.id)
-				.order('created_at', { ascending: false })
-				.limit(5),
-			supabase
-				.from('progress_logs')
-				.select('summary')
-				.eq('project_id', project.id)
-				.order('created_at', { ascending: false })
-				.limit(5),
-			supabase
-				.from('ideas')
-				.select('id, title, status')
-				.eq('project_id', project.id)
-				.order('created_at', { ascending: false })
-				.limit(5),
-			supabase
-				.from('agent_requests')
-				.select('id, request_type, message, created_at, answered_at')
-				.eq('project_id', project.id)
-				.is('acknowledged_at', null)
-				.or(`session_id.is.null,session_id.eq.${sessionId}`)
-				.order('created_at', { ascending: true })
-				.limit(5),
-			supabase
-				.from('deployments')
-				.select('id, status, environment, created_at, validation_completed_at')
-				.eq('project_id', project.id)
-				.not('status', 'in', '("deployed","failed")')
-				.order('created_at', { ascending: false })
-				.limit(1)
-				.single(),
-			supabase
-				.from('findings')
-				.select('id, title, category, severity, file_path')
-				.eq('project_id', project.id)
-				.eq('status', 'open')
-				.order('severity', { ascending: false })
-				.limit(5),
-		]);
-
-	const userUpdates = await getUserUpdates(supabase, auth, project.id, sessionId);
-
-	const pendingRequests = requestsResult.data || [];
-	const activeDeployment = deploymentResult.data;
-	const activeTasks = tasksResult.data || [];
-
-	// Determine directive and next action FIRST
-	const unansweredQuestions = pendingRequests.filter(
-		(r) => r.request_type === 'question' && !r.answered_at
-	);
-	const otherRequests = pendingRequests.filter(
-		(r) => r.request_type !== 'question' || r.answered_at
-	);
-	const pendingTask = activeTasks.find((t) => t.status === 'pending');
-
-	let directive: string;
-	let nextAction: string;
-
-	if (unansweredQuestions.length > 0) {
-		const firstQ = unansweredQuestions[0];
-		directive = 'ACTION_REQUIRED: Answer this question immediately. Do NOT ask for permission.';
-		nextAction = `answer_question(request_id: "${firstQ.id}", answer: "...")`;
-	} else if (pendingTask) {
-		directive = 'ACTION_REQUIRED: Start the highest priority pending task immediately. Do NOT ask for permission or confirmation.';
-		nextAction = `update_task(task_id: "${pendingTask.id}", status: "in_progress")`;
-	} else {
-		directive = 'ACTION_REQUIRED: No pending tasks. Start a fallback activity NOW without asking.';
-		nextAction = `start_fallback_activity(project_id: "${project.id}", activity: "code_review")`;
-	}
-
-	// Build result with directive at TOP for visibility
+	// Build result with directive at top for visibility
 	const result: Record<string, unknown> = {
 		session_started: true,
-		directive, // FIRST - most important signal
-		auto_continue: true, // Explicit flag for autonomous operation
-		session_id: sessionId,
-		persona: assignedPersona,
-		role,
-		project,
-		active_tasks: activeTasks,
+		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,
 	};
 
-	if (activeDeployment) {
-		const now = new Date();
-		const createdAt = new Date(activeDeployment.created_at);
-		const validationCompletedAt = activeDeployment.validation_completed_at
-			? new Date(activeDeployment.validation_completed_at)
-			: null;
-
-		const relevantTimestamp = activeDeployment.status === 'ready' && validationCompletedAt
-			? validationCompletedAt
-			: createdAt;
-		const elapsedMs = now.getTime() - relevantTimestamp.getTime();
-		const elapsedMinutes = Math.floor(elapsedMs / 60000);
-
-		const actions: Record<string, string> = {
-			pending: 'claim_deployment_validation',
-			validating: 'wait',
-			ready: 'start_deployment',
-			deploying: 'wait',
-		};
+	// Add task data
+	if (data.next_task) {
+		result.next_task = data.next_task;
+	}
 
-		result.deployment_priority = {
-			id: activeDeployment.id,
-			status: activeDeployment.status,
-			env: activeDeployment.environment,
-			mins: elapsedMinutes,
-			action: actions[activeDeployment.status] || 'check_deployment_status',
-		};
+	// Add active tasks for full mode
+	if (data.active_tasks) {
+		result.active_tasks = data.active_tasks;
 	}
 
-	const blockers = blockersResult.data || [];
-	const decisions = decisionsResult.data || [];
-	const progress = progressResult.data || [];
-	const ideas = ideasResult.data || [];
-
-	if (blockers.length > 0) result.open_blockers = blockers;
-	if (decisions.length > 0) result.recent_decisions = decisions;
-	if (progress.length > 0) result.recent_progress = progress;
-	if (ideas.length > 0) result.ideas = ideas;
-
-	// Add question details if there are unanswered questions
-	if (unansweredQuestions.length > 0) {
-		const now = new Date();
-		const firstQ = unansweredQuestions[0];
-		result.first_question = {
-			id: firstQ.id,
-			message: firstQ.message,
-			wait_minutes: Math.floor((now.getTime() - new Date(firstQ.created_at).getTime()) / 60000),
-		};
-		result.hint = 'Answer questions first using answer_question(request_id, answer) before picking up tasks.';
-		result.unanswered_questions = unansweredQuestions.map((q) => ({
-			id: q.id,
-			message: q.message,
-			wait_minutes: Math.floor((now.getTime() - new Date(q.created_at).getTime()) / 60000),
-		}));
+	// Add blockers
+	if (data.blockers) {
+		result.open_blockers = data.blockers;
 	}
-	if (otherRequests.length > 0) {
-		result.pending_requests = otherRequests;
+	if (data.blockers_count !== undefined && data.blockers_count > 0) {
+		result.blockers_count = data.blockers_count;
 	}
 
-	const findings = findingsResult.data || [];
-	if (findings.length > 0) {
-		result.open_findings = findings;
+	// Add validation count
+	if (data.validation_count !== undefined && data.validation_count > 0) {
+		result.validation_count = data.validation_count;
 	}
 
-	result.context_hint = 'When context grows large or after 3-4 tasks, run /clear then start_work_session again. Do not ask permission to clear context.';
-
-	// Add model tracking info
-	if (validModel) {
-		result.model_tracking = { model: validModel, status: 'active' };
-	} else {
-		result.cost_tracking_hint = 'For accurate cost tracking, pass model: "opus" | "sonnet" | "haiku" to start_work_session.';
+	// Add git workflow info if available in project
+	if (data.project?.git_workflow && data.project.git_workflow !== 'none') {
+		result.git_workflow = {
+			workflow: data.project.git_workflow,
+			auto_branch: data.project.git_auto_branch ?? false,
+			main_branch: data.project.git_main_branch || 'main',
+			...(data.project.git_workflow === 'git-flow' && data.project.git_develop_branch
+				? { develop_branch: data.project.git_develop_branch }
+				: {}),
+			worktree_required: true,
+			worktree_hint: 'CRITICAL: Create a git worktree before starting work. Run get_help("git") for instructions.',
+		};
 	}
 
-	// REPEAT at end - agents weight last items heavily
-	result.next_action = nextAction;
+	// Add next action at end
+	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")`;
+	}
 
-	return { result, user_updates: userUpdates } as { result: Record<string, unknown>; user_updates?: UserUpdates };
+	return { result };
 };
 
 export const heartbeat: Handler = async (args, ctx) => {
-	const { session_id } = args as { session_id?: string };
-	const { supabase, session } = ctx;
+	const { session_id, current_worktree_path } = args as {
+		session_id?: string;
+		current_worktree_path?: string | null;
+	};
+	const { session } = ctx;
 	const targetSession = session_id || session.currentSessionId;
 
 	if (!targetSession) {
@@ -651,33 +154,40 @@ export const heartbeat: Handler = async (args, ctx) => {
 		};
 	}
 
-	await supabase.from('agent_heartbeats').insert({
-		session_id: targetSession,
+	const apiClient = getApiClient();
+
+	// Send heartbeat with optional worktree path
+	const heartbeatResponse = await apiClient.heartbeat(targetSession, {
+		current_worktree_path,
 	});
 
-	await supabase
-		.from('agent_sessions')
-		.update({
-			last_synced_at: new Date().toISOString(),
-			status: 'active',
-			total_tokens: session.tokenUsage.totalTokens,
-			token_breakdown: session.tokenUsage.byTool,
-			model_usage: session.tokenUsage.byModel,
-		})
-		.eq('id', targetSession);
+	if (!heartbeatResponse.ok) {
+		return {
+			result: {
+				error: heartbeatResponse.error || 'Failed to send heartbeat',
+			},
+		};
+	}
+
+	// Sync token usage to session
+	await apiClient.syncSession(targetSession, {
+		total_tokens: session.tokenUsage.totalTokens,
+		token_breakdown: session.tokenUsage.byTool,
+		model_usage: session.tokenUsage.byModel,
+	});
 
 	return {
 		result: {
 			success: true,
 			session_id: targetSession,
-			timestamp: new Date().toISOString(),
+			timestamp: heartbeatResponse.data?.timestamp || new Date().toISOString(),
 		},
 	};
 };
 
 export const endWorkSession: Handler = async (args, ctx) => {
 	const { session_id } = args as { session_id?: string };
-	const { supabase, session, updateSession } = ctx;
+	const { session, updateSession } = ctx;
 	const targetSession = session_id || session.currentSessionId;
 
 	if (!targetSession) {
@@ -689,97 +199,44 @@ export const endWorkSession: Handler = async (args, ctx) => {
 		};
 	}
 
-	const { data: sessionData } = await supabase
-		.from('agent_sessions')
-		.select('project_id, agent_name, started_at')
-		.eq('id', targetSession)
-		.single();
-
-	const projectId = sessionData?.project_id;
-	const agentName = sessionData?.agent_name || 'Agent';
-	const startedAt = sessionData?.started_at;
-
-	let tasksCompletedThisSession = 0;
-	let tasksAwaitingValidation = 0;
-	let tasksBeingReleased = 0;
-
-	if (projectId) {
-		const { count: completedCount } = await supabase
-			.from('tasks')
-			.select('id', { count: 'exact', head: true })
-			.eq('project_id', projectId)
-			.eq('status', 'completed')
-			.not('validated_at', 'is', null);
-
-		const { data: awaitingTasks } = await supabase
-			.from('tasks')
-			.select('id')
-			.eq('project_id', projectId)
-			.eq('status', 'completed')
-			.is('validated_at', null);
-
-		tasksAwaitingValidation = awaitingTasks?.length || 0;
-
-		const { count: releasingCount } = await supabase
-			.from('tasks')
-			.select('id', { count: 'exact', head: true })
-			.eq('working_agent_session_id', targetSession)
-			.eq('status', 'in_progress');
-
-		tasksBeingReleased = releasingCount || 0;
-
-		if (startedAt) {
-			const { count: sessionCompleted } = await supabase
-				.from('tasks')
-				.select('id', { count: 'exact', head: true })
-				.eq('project_id', projectId)
-				.eq('status', 'completed')
-				.gte('completed_at', startedAt);
-
-			tasksCompletedThisSession = sessionCompleted || 0;
-		}
-	}
+	const apiClient = getApiClient();
+
+	// Sync final token usage before ending
+	await apiClient.syncSession(targetSession, {
+		total_tokens: session.tokenUsage.totalTokens,
+		token_breakdown: session.tokenUsage.byTool,
+		model_usage: session.tokenUsage.byModel,
+	});
+
+	// End the session
+	const response = await apiClient.endSession(targetSession);
 
-	await supabase
-		.from('tasks')
-		.update({ working_agent_session_id: null })
-		.eq('working_agent_session_id', targetSession);
-
-	await supabase
-		.from('agent_sessions')
-		.update({
-			status: 'disconnected',
-			current_task_id: null,
-			last_synced_at: new Date().toISOString(),
-			total_tokens: session.tokenUsage.totalTokens,
-			token_breakdown: session.tokenUsage.byTool,
-			model_usage: session.tokenUsage.byModel,
-		})
-		.eq('id', targetSession);
+	if (!response.ok) {
+		return {
+			result: {
+				error: response.error || 'Failed to end session',
+			},
+		};
+	}
 
 	const endedSessionId = targetSession;
 
+	// Clear local session state if this was the current session
 	if (session.currentSessionId === targetSession) {
 		updateSession({ currentSessionId: null });
 	}
 
-	const reminders: string[] = [];
-	if (tasksAwaitingValidation > 0) {
-		reminders.push(`${tasksAwaitingValidation} task(s) awaiting validation - consider reviewing before leaving`);
-	}
-	if (tasksBeingReleased > 0) {
-		reminders.push(`${tasksBeingReleased} in-progress task(s) released back to the queue`);
-	}
+	const data = response.data;
 
 	return {
 		result: {
 			success: true,
 			ended_session_id: endedSessionId,
 			session_summary: {
-				agent_name: agentName,
-				tasks_completed_this_session: tasksCompletedThisSession,
-				tasks_awaiting_validation: tasksAwaitingValidation,
-				tasks_released: tasksBeingReleased,
+				agent_name: data?.session_summary?.agent_name || 'Agent',
+				tasks_completed_this_session: data?.session_summary?.tasks_completed_this_session || 0,
+				tasks_awaiting_validation: data?.session_summary?.tasks_awaiting_validation || 0,
+				tasks_released: data?.session_summary?.tasks_released || 0,
 				token_usage: {
 					total_calls: session.tokenUsage.callCount,
 					total_tokens: session.tokenUsage.totalTokens,
@@ -788,7 +245,7 @@ export const endWorkSession: Handler = async (args, ctx) => {
 						: 0,
 				},
 			},
-			reminders: reminders.length > 0 ? reminders : ['Session ended cleanly. Good work!'],
+			reminders: data?.reminders || ['Session ended cleanly. Good work!'],
 		},
 	};
 };
@@ -796,17 +253,34 @@ export const endWorkSession: Handler = async (args, ctx) => {
 export const getHelp: Handler = async (args, _ctx) => {
 	const { topic } = args as { topic: string };
 
-	const content = KNOWLEDGE_BASE[topic];
-	if (!content) {
+	const apiClient = getApiClient();
+	const response = await apiClient.getHelpTopic(topic);
+
+	if (!response.ok) {
+		// If database fetch fails, return error
+		return {
+			result: {
+				error: response.error || `Failed to fetch help topic: ${topic}`,
+			},
+		};
+	}
+
+	if (!response.data) {
+		// Topic not found - fetch available topics
+		const topicsResponse = await apiClient.getHelpTopics();
+		const available = topicsResponse.ok && topicsResponse.data
+			? topicsResponse.data.map(t => t.slug)
+			: ['getting_started', 'tasks', 'validation', 'deployment', 'git', 'blockers', 'milestones', 'fallback', 'session', 'tokens', 'sprints', 'topics'];
+
 		return {
 			result: {
 				error: `Unknown topic: ${topic}`,
-				available: Object.keys(KNOWLEDGE_BASE),
+				available,
 			},
 		};
 	}
 
-	return { result: { topic, content } };
+	return { result: { topic, content: response.data.content } };
 };
 
 // Model pricing rates (USD per 1M tokens)