@vibescope/mcp-server 0.2.3 → 0.2.5

package/src/handlers/session.ts

@@ -1,425 +1,738 @@
-/**
- * Session Handlers
- *
- * Handles agent session lifecycle:
- * - start_work_session
- * - heartbeat
- * - end_work_session
- * - get_help
- * - get_token_usage
- */
-
-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, 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 && VALID_MODELS.includes(normalizedModel as SessionModel)
-		? normalizedModel
-		: null;
-
-	updateSession({
-		tokenUsage: {
-			callCount: 0,
-			totalTokens: 0,
-			byTool: {},
-			byModel: {},
-			currentModel: validModel,
-		},
-	});
-
-	// Require project_id or git_url
-	if (!project_id && !git_url) {
-		return {
-			result: {
-				error: 'Please provide project_id or git_url to start a session',
-			},
-		};
-	}
-
-	const apiClient = getApiClient();
-	const response = await apiClient.startSession({
-		project_id,
-		git_url,
-		mode: mode as SessionMode,
-		model: model as SessionModel | undefined,
-		role: role as SessionRole
-	});
-
-	if (!response.ok) {
-		return {
-			result: {
-				error: response.error || 'Failed to start session',
-			},
-		};
-	}
-
-	const data = response.data;
-
-	// Handle project not found
-	if (!data?.session_started) {
-		return { result: data };
-	}
-
-	// Store session ID and persona in local state
-	if (data.session_id) {
-		updateSession({
-			currentSessionId: data.session_id,
-			currentPersona: data.persona || null,
-		});
-	}
-
-	// Check for unanswered questions - these MUST be handled first
-	const hasUnansweredQuestions = data.unanswered_questions_count && data.unanswered_questions_count > 0;
-
-	// Build result
-	const result: Record<string, unknown> = {
-		session_started: true,
-	};
-
-	// Directive comes first
-	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 unanswered questions count (not full array - agent can fetch details when needed)
-	if (hasUnansweredQuestions) {
-		result.unanswered_questions_count = data.unanswered_questions_count;
-	}
-
-	// Add active tasks for full mode
-	if (data.active_tasks) {
-		result.active_tasks = data.active_tasks;
-	}
-
-	// Add blockers
-	if (data.blockers) {
-		result.open_blockers = data.blockers;
-	}
-	if (data.blockers_count !== undefined && data.blockers_count > 0) {
-		result.blockers_count = data.blockers_count;
-	}
-
-	// Add validation count
-	if (data.validation_count !== undefined && data.validation_count > 0) {
-		result.validation_count = data.validation_count;
-	}
-
-	// 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.',
-		};
-	}
-
-	// 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")`;
-	}
-
-	return { result };
-};
-
-export const heartbeat: Handler = async (args, ctx) => {
-	const { session_id, current_worktree_path } = parseArgs(args, heartbeatSchema);
-	const { session } = ctx;
-	const targetSession = session_id || session.currentSessionId;
-
-	if (!targetSession) {
-		return {
-			result: {
-				error: 'No active session. Call start_work_session first.',
-			},
-		};
-	}
-
-	const apiClient = getApiClient();
-
-	// Send heartbeat with optional worktree path
-	const heartbeatResponse = await apiClient.heartbeat(targetSession, {
-		current_worktree_path,
-	});
-
-	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: heartbeatResponse.data?.timestamp || new Date().toISOString(),
-		},
-	};
-};
-
-export const endWorkSession: Handler = async (args, ctx) => {
-	const { session_id } = parseArgs(args, endWorkSessionSchema);
-	const { session, updateSession } = ctx;
-	const targetSession = session_id || session.currentSessionId;
-
-	if (!targetSession) {
-		return {
-			result: {
-				success: true,
-				message: 'No active session to end',
-			},
-		};
-	}
-
-	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);
-
-	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 data = response.data;
-
-	return {
-		result: {
-			success: true,
-			ended_session_id: endedSessionId,
-			session_summary: {
-				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,
-					avg_per_call: session.tokenUsage.callCount > 0
-						? Math.round(session.tokenUsage.totalTokens / session.tokenUsage.callCount)
-						: 0,
-				},
-			},
-			reminders: data?.reminders || ['Session ended cleanly. Good work!'],
-		},
-	};
-};
-
-export const getHelp: Handler = async (args, _ctx) => {
-	const { topic } = parseArgs(args, getHelpSchema);
-
-	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,
-			},
-		};
-	}
-
-	return { result: { topic, content: response.data.content } };
-};
-
-// Model pricing rates (USD per 1M tokens)
-const MODEL_PRICING: Record<string, { input: number; output: number }> = {
-	opus: { input: 15.0, output: 75.0 },
-	sonnet: { input: 3.0, output: 15.0 },
-	haiku: { input: 0.25, output: 1.25 },
-};
-
-function calculateCost(byModel: Record<string, { input: number; output: number }>): {
-	breakdown: Record<string, { input_cost: number; output_cost: number; total: number }>;
-	total: number;
-} {
-	const breakdown: Record<string, { input_cost: number; output_cost: number; total: number }> = {};
-	let total = 0;
-
-	for (const [model, tokens] of Object.entries(byModel)) {
-		const pricing = MODEL_PRICING[model];
-		if (pricing) {
-			const inputCost = (tokens.input / 1_000_000) * pricing.input;
-			const outputCost = (tokens.output / 1_000_000) * pricing.output;
-			const modelTotal = inputCost + outputCost;
-			breakdown[model] = {
-				input_cost: Math.round(inputCost * 10000) / 10000,
-				output_cost: Math.round(outputCost * 10000) / 10000,
-				total: Math.round(modelTotal * 10000) / 10000,
-			};
-			total += modelTotal;
-		}
-	}
-
-	return { breakdown, total: Math.round(total * 10000) / 10000 };
-}
-
-export const getTokenUsage: Handler = async (_args, ctx) => {
-	const { session } = ctx;
-	const sessionTokenUsage = session.tokenUsage;
-
-	const topTools = Object.entries(sessionTokenUsage.byTool)
-		.sort(([, a], [, b]) => b.tokens - a.tokens)
-		.slice(0, 5)
-		.map(([tool, stats]) => ({
-			tool,
-			calls: stats.calls,
-			tokens: stats.tokens,
-			avg: Math.round(stats.tokens / stats.calls),
-		}));
-
-	// Calculate model breakdown and costs
-	const modelBreakdown = Object.entries(sessionTokenUsage.byModel || {}).map(([model, tokens]) => ({
-		model,
-		input_tokens: tokens.input,
-		output_tokens: tokens.output,
-		total_tokens: tokens.input + tokens.output,
-	}));
-
-	const costData = calculateCost(sessionTokenUsage.byModel || {});
-
-	// If no model tracking, estimate cost assuming sonnet (middle tier)
-	const estimatedCostNoModel = Object.keys(sessionTokenUsage.byModel || {}).length === 0
-		? Math.round((sessionTokenUsage.totalTokens / 1_000_000) * MODEL_PRICING.sonnet.output * 10000) / 10000
-		: null;
-
-	// Add context clearing directive when usage is high
-	const shouldClearContext = sessionTokenUsage.callCount > 50 || sessionTokenUsage.totalTokens > 100000;
-
-	return {
-		result: {
-			session: {
-				calls: sessionTokenUsage.callCount,
-				tokens: sessionTokenUsage.totalTokens,
-				avg_per_call: sessionTokenUsage.callCount > 0
-					? Math.round(sessionTokenUsage.totalTokens / sessionTokenUsage.callCount)
-					: 0,
-				current_model: sessionTokenUsage.currentModel,
-			},
-			top_tools: topTools,
-			model_breakdown: modelBreakdown.length > 0 ? modelBreakdown : undefined,
-			cost: {
-				by_model: Object.keys(costData.breakdown).length > 0 ? costData.breakdown : undefined,
-				total_usd: costData.total > 0 ? costData.total : estimatedCostNoModel,
-				estimated: estimatedCostNoModel !== null,
-			},
-			note: sessionTokenUsage.currentModel
-				? `Tracking ${sessionTokenUsage.currentModel} model usage. Token estimates ~4 chars/token.`
-				: 'Token estimates based on response size (~4 chars/token). Set model in start_work_session for accurate costs.',
-			...(shouldClearContext && {
-				directive: 'High token usage detected. Run /clear then start_work_session to reset context. Do not ask permission.',
-			}),
-		},
-	};
-};
-
-/**
- * Session handlers registry
- */
-export const sessionHandlers: HandlerRegistry = {
-	start_work_session: startWorkSession,
-	heartbeat: heartbeat,
-	end_work_session: endWorkSession,
-	get_help: getHelp,
-	get_token_usage: getTokenUsage,
-};
+/**
+ * Session Handlers
+ *
+ * Handles agent session lifecycle:
+ * - start_work_session
+ * - heartbeat
+ * - end_work_session
+ * - get_help
+ * - get_token_usage
+ */
+
+import os from 'os';
+import type { Handler, HandlerRegistry, TokenUsage } from './types.js';
+import { parseArgs, createEnumValidator } from '../validators.js';
+import { getApiClient } from '../api-client.js';
+import { getAgentGuidelinesTemplate, getAgentGuidelinesSummary } from '../templates/agent-guidelines.js';
+
+// Auto-detect machine hostname for worktree tracking
+const MACHINE_HOSTNAME = os.hostname();
+
+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;
+const VALID_AGENT_TYPES = ['claude', 'gemini', 'cursor', 'windsurf', 'other'] as const;
+
+type SessionMode = typeof VALID_MODES[number];
+type SessionModel = typeof VALID_MODELS[number];
+type SessionRole = typeof VALID_ROLES[number];
+type AgentType = typeof VALID_AGENT_TYPES[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) },
+	hostname: { type: 'string' as const }, // Machine hostname for worktree tracking
+	agent_type: { type: 'string' as const, validate: createEnumValidator(VALID_AGENT_TYPES) }, // Agent type for onboarding
+};
+
+const heartbeatSchema = {
+	session_id: { type: 'string' as const },
+	current_worktree_path: { type: 'string' as const },
+	hostname: { type: 'string' as const }, // Machine hostname for worktree tracking
+};
+
+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, model, role, hostname: providedHostname, agent_type } = parseArgs(args, startWorkSessionSchema);
+
+	// Use auto-detected hostname if not provided - enables machine-aware worktree filtering
+	const hostname = providedHostname || MACHINE_HOSTNAME;
+
+	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 && VALID_MODELS.includes(normalizedModel as SessionModel)
+		? normalizedModel
+		: null;
+
+	updateSession({
+		tokenUsage: {
+			callCount: 0,
+			totalTokens: 0,
+			byTool: {},
+			byModel: {},
+			currentModel: validModel,
+		},
+	});
+
+	// Require project_id or git_url
+	if (!project_id && !git_url) {
+		return {
+			result: {
+				error: 'Please provide project_id or git_url to start a session',
+				session_termination_required: true,
+				reason: 'Cannot start work without identifying a project',
+				action: 'END_SESSION_NOW - Do not proceed with any work until MCP is properly configured.',
+			},
+		};
+	}
+
+	const apiClient = getApiClient();
+	const response = await apiClient.startSession({
+		project_id,
+		git_url,
+		mode: mode as SessionMode,
+		model: model as SessionModel | undefined,
+		role: role as SessionRole,
+		hostname, // Machine hostname for worktree tracking
+		agent_type: agent_type as AgentType | undefined, // Agent type for onboarding
+	});
+
+	if (!response.ok) {
+		// Include additional error details if available
+		const errorData = response.data as { detail?: string; code?: string } | undefined;
+		return {
+			result: {
+				error: response.error || 'Failed to start session',
+				...(errorData?.detail && { detail: errorData.detail }),
+				...(errorData?.code && { code: errorData.code }),
+				session_termination_required: true,
+				reason: 'MCP server connection failed - cannot track work',
+				action: 'END_SESSION_NOW - Do not proceed with any work.',
+				troubleshooting: [
+					'1. Check if MCP server is configured: claude mcp list',
+					'2. Verify VIBESCOPE_API_KEY is set correctly',
+					'3. Check network connectivity to vibescope.dev',
+					'4. Restart Claude Code after fixing configuration',
+				],
+				user_message: 'MCP connection to Vibescope failed. I cannot proceed without task tracking. Please fix the configuration and restart.',
+			},
+		};
+	}
+
+	const data = response.data;
+
+	// Handle project not found - include agent guidelines for new project setup
+	if (!data?.session_started) {
+		// If project_not_found, include agent guidelines template for CLAUDE.md setup
+		if (data?.project_not_found) {
+			return {
+				result: {
+					...data,
+					agent_guidelines: {
+						message: 'IMPORTANT: After creating the project, add these guidelines to your .claude/CLAUDE.md file.',
+						summary: getAgentGuidelinesSummary(),
+						full_template: getAgentGuidelinesTemplate(),
+						setup_instructions: [
+							'1. Create the project using create_project()',
+							'2. Create .claude/CLAUDE.md in your project root',
+							'3. Copy the full_template content into CLAUDE.md',
+							'4. Call start_work_session again to begin work',
+						],
+					},
+				},
+			};
+		}
+		return { result: data };
+	}
+
+	// Store session ID and persona in local state
+	if (data.session_id) {
+		updateSession({
+			currentSessionId: data.session_id,
+			currentPersona: data.persona || null,
+		});
+	}
+
+	// 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,
+	};
+
+	// 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;
+	}
+
+	// Add blockers
+	if (data.blockers) {
+		result.open_blockers = data.blockers;
+	}
+	if (data.blockers_count !== undefined && data.blockers_count > 0) {
+		result.blockers_count = data.blockers_count;
+	}
+
+	// Add validation tasks when present - agents should validate before starting new work
+	if (data.validation_count !== undefined && data.validation_count > 0) {
+		result.validation_count = data.validation_count;
+	}
+	if (data.awaiting_validation && data.awaiting_validation.length > 0) {
+		result.awaiting_validation = data.awaiting_validation;
+		result.validation_priority = data.validation_priority;
+	}
+
+	// Add stale worktrees warning if any exist
+	if (data.stale_worktrees && data.stale_worktrees.length > 0) {
+		result.stale_worktrees = data.stale_worktrees;
+		result.stale_worktrees_count = data.stale_worktrees_count;
+		result.cleanup_action = data.cleanup_action;
+	}
+
+	// Add git workflow info if available in project
+	if (data.project?.git_workflow && data.project.git_workflow !== 'none') {
+		// Branching workflows (git-flow, github-flow) require worktrees
+		// Trunk-based development commits directly to main, no worktree needed
+		const isBranchingWorkflow = data.project.git_workflow === 'git-flow' || data.project.git_workflow === 'github-flow';
+		const baseBranch = data.project.git_workflow === 'git-flow'
+			? (data.project.git_develop_branch || 'develop')
+			: (data.project.git_main_branch || 'main');
+
+		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: isBranchingWorkflow,
+		};
+
+		// Only show worktree reminder for branching workflows (git-flow, github-flow)
+		if (isBranchingWorkflow) {
+			result.WORKTREE_REMINDER = {
+				message: 'CRITICAL: Create worktree BEFORE making ANY file edits',
+				wrong_order: 'DO NOT: Edit files → stash → create worktree → pop stash',
+				right_order: 'DO: Create worktree → cd into it → THEN edit files',
+				command: `git worktree add ../<project>-<persona>-<task> -b feature/<task-id> ${baseBranch}`,
+				help: 'Run get_help("git") for full instructions',
+			};
+		}
+	}
+
+	// Add agent setup instructions if this is a new agent type for the project
+	if (data.agent_setup) {
+		result.agent_setup = data.agent_setup;
+		// If setup is required, update directive to prioritize setup
+		if (data.agent_setup.setup_required) {
+			result.directive = `SETUP REQUIRED: This is your first time connecting as a ${data.agent_setup.agent_type} agent. Follow the agent_setup instructions before starting work.`;
+		}
+	}
+
+	// Add next action at end - pending requests take priority over validation, then regular 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.awaiting_validation && data.awaiting_validation.length > 0) {
+		// Validation tasks take priority over new work - use next_action from API if available
+		result.next_action = data.next_action || `claim_validation(task_id: "${data.awaiting_validation[0].id}")`;
+	} 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")`;
+	}
+
+	return { result };
+};
+
+export const heartbeat: Handler = async (args, ctx) => {
+	const { session_id, current_worktree_path, hostname: providedHostname } = parseArgs(args, heartbeatSchema);
+	const { session } = ctx;
+	const targetSession = session_id || session.currentSessionId;
+
+	// Use auto-detected hostname if not provided
+	const hostname = providedHostname || MACHINE_HOSTNAME;
+
+	if (!targetSession) {
+		return {
+			result: {
+				error: 'No active session. Call start_work_session first.',
+			},
+		};
+	}
+
+	const apiClient = getApiClient();
+
+	// Send heartbeat with optional worktree path and hostname
+	const heartbeatResponse = await apiClient.heartbeat(targetSession, {
+		current_worktree_path,
+		hostname,
+	});
+
+	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: heartbeatResponse.data?.timestamp || new Date().toISOString(),
+		},
+	};
+};
+
+export const endWorkSession: Handler = async (args, ctx) => {
+	const { session_id } = parseArgs(args, endWorkSessionSchema);
+	const { session, updateSession } = ctx;
+	const targetSession = session_id || session.currentSessionId;
+
+	if (!targetSession) {
+		return {
+			result: {
+				success: true,
+				message: 'No active session to end',
+			},
+		};
+	}
+
+	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);
+
+	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 data = response.data;
+
+	return {
+		result: {
+			success: true,
+			ended_session_id: endedSessionId,
+			session_summary: {
+				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,
+					avg_per_call: session.tokenUsage.callCount > 0
+						? Math.round(session.tokenUsage.totalTokens / session.tokenUsage.callCount)
+						: 0,
+				},
+			},
+			reminders: data?.reminders || ['Session ended cleanly. Good work!'],
+		},
+	};
+};
+
+export const getHelp: Handler = async (args, _ctx) => {
+	const { topic } = parseArgs(args, getHelpSchema);
+
+	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,
+			},
+		};
+	}
+
+	return { result: { topic, content: response.data.content } };
+};
+
+// Model pricing rates (USD per 1M tokens) by pricing tier
+// 'standard' = regular API rates (included in Max plans)
+// 'extra_usage' = overage rates when exceeding plan limits (currently same as standard)
+export type PricingTier = 'standard' | 'extra_usage';
+
+interface ModelPricing {
+	input: number;
+	output: number;
+	description?: string;
+}
+
+const MODEL_PRICING: Record<PricingTier, Record<string, ModelPricing>> = {
+	standard: {
+		// Claude models
+		opus: { input: 15.0, output: 75.0, description: 'Claude Opus 4.5' },
+		sonnet: { input: 3.0, output: 15.0, description: 'Claude Sonnet 4' },
+		haiku: { input: 0.25, output: 1.25, description: 'Claude Haiku 3.5' },
+		// Gemini models (as of Jan 2025)
+		gemini: { input: 0.10, output: 0.40, description: 'Gemini 2.0 Flash' },
+		'gemini-2.0-flash': { input: 0.10, output: 0.40, description: 'Gemini 2.0 Flash' },
+		'gemini-1.5-pro': { input: 1.25, output: 5.00, description: 'Gemini 1.5 Pro' },
+		'gemini-1.5-flash': { input: 0.075, output: 0.30, description: 'Gemini 1.5 Flash' },
+	},
+	extra_usage: {
+		// Claude models - extra usage/overage rates (same as standard for now)
+		opus: { input: 15.0, output: 75.0, description: 'Claude Opus 4.5 - Extra usage' },
+		sonnet: { input: 3.0, output: 15.0, description: 'Claude Sonnet 4 - Extra usage' },
+		haiku: { input: 0.25, output: 1.25, description: 'Claude Haiku 3.5 - Extra usage' },
+		// Gemini models - extra usage rates (same as standard for now)
+		gemini: { input: 0.10, output: 0.40, description: 'Gemini 2.0 Flash - Extra usage' },
+		'gemini-2.0-flash': { input: 0.10, output: 0.40, description: 'Gemini 2.0 Flash - Extra usage' },
+		'gemini-1.5-pro': { input: 1.25, output: 5.00, description: 'Gemini 1.5 Pro - Extra usage' },
+		'gemini-1.5-flash': { input: 0.075, output: 0.30, description: 'Gemini 1.5 Flash - Extra usage' },
+	},
+};
+
+// Legacy accessor for backward compatibility
+const getModelPricing = (tier: PricingTier = 'standard') => MODEL_PRICING[tier];
+
+function calculateCost(
+	byModel: Record<string, { input: number; output: number }>,
+	tier: PricingTier = 'standard'
+): {
+	breakdown: Record<string, { input_cost: number; output_cost: number; total: number; description?: string }>;
+	total: number;
+	pricing_tier: PricingTier;
+} {
+	const breakdown: Record<string, { input_cost: number; output_cost: number; total: number; description?: string }> = {};
+	let total = 0;
+	const pricingTable = getModelPricing(tier);
+
+	for (const [model, tokens] of Object.entries(byModel)) {
+		const pricing = pricingTable[model];
+		if (pricing) {
+			const inputCost = (tokens.input / 1_000_000) * pricing.input;
+			const outputCost = (tokens.output / 1_000_000) * pricing.output;
+			const modelTotal = inputCost + outputCost;
+			breakdown[model] = {
+				input_cost: Math.round(inputCost * 10000) / 10000,
+				output_cost: Math.round(outputCost * 10000) / 10000,
+				total: Math.round(modelTotal * 10000) / 10000,
+				description: pricing.description,
+			};
+			total += modelTotal;
+		}
+	}
+
+	return { breakdown, total: Math.round(total * 10000) / 10000, pricing_tier: tier };
+}
+
+export const getTokenUsage: Handler = async (_args, ctx) => {
+	const { session } = ctx;
+	const sessionTokenUsage = session.tokenUsage;
+
+	const topTools = Object.entries(sessionTokenUsage.byTool)
+		.sort(([, a], [, b]) => b.tokens - a.tokens)
+		.slice(0, 5)
+		.map(([tool, stats]) => ({
+			tool,
+			calls: stats.calls,
+			tokens: stats.tokens,
+			avg: Math.round(stats.tokens / stats.calls),
+		}));
+
+	// Calculate model breakdown and costs for both pricing tiers
+	const modelBreakdown = Object.entries(sessionTokenUsage.byModel || {}).map(([model, tokens]) => ({
+		model,
+		input_tokens: tokens.input,
+		output_tokens: tokens.output,
+		total_tokens: tokens.input + tokens.output,
+	}));
+
+	const standardCost = calculateCost(sessionTokenUsage.byModel || {}, 'standard');
+	const extraUsageCost = calculateCost(sessionTokenUsage.byModel || {}, 'extra_usage');
+
+	// If no model tracking, estimate cost assuming sonnet (middle tier)
+	const hasModelData = Object.keys(sessionTokenUsage.byModel || {}).length > 0;
+	const estimatedCostNoModel = !hasModelData
+		? Math.round((sessionTokenUsage.totalTokens / 1_000_000) * getModelPricing('standard').sonnet.output * 10000) / 10000
+		: null;
+
+	// Add context clearing directive when usage is high
+	const shouldClearContext = sessionTokenUsage.callCount > 50 || sessionTokenUsage.totalTokens > 100000;
+
+	return {
+		result: {
+			session: {
+				calls: sessionTokenUsage.callCount,
+				tokens: sessionTokenUsage.totalTokens,
+				avg_per_call: sessionTokenUsage.callCount > 0
+					? Math.round(sessionTokenUsage.totalTokens / sessionTokenUsage.callCount)
+					: 0,
+				current_model: sessionTokenUsage.currentModel,
+			},
+			top_tools: topTools,
+			model_breakdown: modelBreakdown.length > 0 ? modelBreakdown : undefined,
+			cost: {
+				// Standard tier (optimistic - included in Max plan)
+				standard: {
+					by_model: Object.keys(standardCost.breakdown).length > 0 ? standardCost.breakdown : undefined,
+					total_usd: standardCost.total > 0 ? standardCost.total : estimatedCostNoModel,
+					pricing_tier: 'standard',
+				},
+				// Extra usage tier (pessimistic - overage rates)
+				extra_usage: {
+					by_model: Object.keys(extraUsageCost.breakdown).length > 0 ? extraUsageCost.breakdown : undefined,
+					total_usd: extraUsageCost.total > 0 ? extraUsageCost.total : estimatedCostNoModel,
+					pricing_tier: 'extra_usage',
+				},
+				// Legacy field for backward compatibility
+				total_usd: standardCost.total > 0 ? standardCost.total : estimatedCostNoModel,
+				estimated: estimatedCostNoModel !== null,
+			},
+			supported_models: {
+				claude: ['opus', 'sonnet', 'haiku'],
+				gemini: ['gemini', 'gemini-2.0-flash', 'gemini-1.5-pro', 'gemini-1.5-flash'],
+			},
+			note: 'IMPORTANT: These estimates only track MCP tool I/O (~1-5% of actual API usage). Actual costs may be 20-100x higher due to conversation context, system prompts, and reasoning tokens. Use report_token_usage() with actual API response values for accurate tracking.',
+			estimation_coverage: 'mcp_tool_io_only',
+			...(shouldClearContext && {
+				directive: 'High token usage detected. Run /clear then start_work_session to reset context. Do not ask permission.',
+			}),
+		},
+	};
+};
+
+const reportTokenUsageSchema = {
+	input_tokens: { type: 'number' as const, required: true as const },
+	output_tokens: { type: 'number' as const, required: true as const },
+	model: { type: 'string' as const, validate: createEnumValidator(VALID_MODELS) },
+};
+
+const confirmAgentSetupSchema = {
+	project_id: { type: 'string' as const, required: true as const },
+	agent_type: { type: 'string' as const, required: true as const, validate: createEnumValidator(VALID_AGENT_TYPES) },
+};
+
+/**
+ * Report actual Claude API token usage for accurate cost tracking.
+ * This allows agents to report their actual API usage instead of relying on MCP estimates.
+ * The backend will attribute costs to the current task if one is active.
+ */
+export const reportTokenUsage: Handler = async (args, ctx) => {
+	const { input_tokens, output_tokens, model } = parseArgs(args, reportTokenUsageSchema);
+	const { session, updateSession } = ctx;
+
+	// Validate token counts
+	if (input_tokens! < 0 || output_tokens! < 0) {
+		return {
+			result: {
+				error: 'Token counts must be non-negative',
+			},
+		};
+	}
+
+	// Determine which model to attribute to
+	const targetModel = model || session.tokenUsage.currentModel || 'sonnet';
+
+	// Update the session's local token usage
+	const updatedByModel = { ...session.tokenUsage.byModel };
+	if (!updatedByModel[targetModel]) {
+		updatedByModel[targetModel] = { input: 0, output: 0 };
+	}
+	updatedByModel[targetModel].input += input_tokens!;
+	updatedByModel[targetModel].output += output_tokens!;
+
+	const totalTokens = input_tokens! + output_tokens!;
+
+	updateSession({
+		tokenUsage: {
+			...session.tokenUsage,
+			callCount: session.tokenUsage.callCount + 1,
+			totalTokens: session.tokenUsage.totalTokens + totalTokens,
+			byModel: updatedByModel,
+		},
+	});
+
+	// Report to backend - this handles both session update and task cost attribution
+	const apiClient = getApiClient();
+	const currentSessionId = session.currentSessionId;
+
+	if (!currentSessionId) {
+		// Calculate cost locally if no session (use standard tier)
+		const pricing = getModelPricing('standard')[targetModel];
+		const inputCost = pricing ? (input_tokens! / 1_000_000) * pricing.input : 0;
+		const outputCost = pricing ? (output_tokens! / 1_000_000) * pricing.output : 0;
+
+		return {
+			result: {
+				success: true,
+				reported: {
+					model: targetModel,
+					input_tokens: input_tokens!,
+					output_tokens: output_tokens!,
+					total_tokens: totalTokens,
+					estimated_cost_usd: Math.round((inputCost + outputCost) * 10000) / 10000,
+				},
+				note: 'Token usage recorded locally. Start a session to attribute costs to your project.',
+			},
+		};
+	}
+
+	// Call the backend to report and attribute costs
+	const response = await apiClient.reportTokenUsage(currentSessionId, {
+		input_tokens: input_tokens!,
+		output_tokens: output_tokens!,
+		model: targetModel as 'opus' | 'sonnet' | 'haiku',
+	});
+
+	if (!response.ok) {
+		// Fall back to local calculation on error (use standard tier)
+		const pricing = getModelPricing('standard')[targetModel];
+		const inputCost = pricing ? (input_tokens! / 1_000_000) * pricing.input : 0;
+		const outputCost = pricing ? (output_tokens! / 1_000_000) * pricing.output : 0;
+
+		return {
+			result: {
+				success: true,
+				reported: {
+					model: targetModel,
+					input_tokens: input_tokens!,
+					output_tokens: output_tokens!,
+					total_tokens: totalTokens,
+					estimated_cost_usd: Math.round((inputCost + outputCost) * 10000) / 10000,
+				},
+				warning: 'Backend sync failed. Token usage recorded locally only.',
+			},
+		};
+	}
+
+	const data = response.data!;
+
+	return {
+		result: {
+			success: true,
+			reported: data.reported,
+			task_attributed: data.task_attributed,
+			...(data.task_id && { task_id: data.task_id }),
+			note: data.task_attributed
+				? 'Token usage recorded and attributed to current task for per-task cost tracking.'
+				: 'Token usage recorded to session. No active task to attribute costs to.',
+		},
+	};
+};
+
+/**
+ * Confirm that agent setup is complete for a project.
+ * This marks the agent type as onboarded, so future sessions won't receive setup instructions.
+ */
+export const confirmAgentSetup: Handler = async (args, _ctx) => {
+	const { project_id, agent_type } = parseArgs(args, confirmAgentSetupSchema);
+
+	if (!project_id || !agent_type) {
+		return {
+			result: {
+				error: 'project_id and agent_type are required',
+			},
+		};
+	}
+
+	const apiClient = getApiClient();
+	const response = await apiClient.confirmAgentSetup(project_id, agent_type as AgentType);
+
+	if (!response.ok) {
+		return {
+			result: {
+				error: response.error || 'Failed to confirm agent setup',
+			},
+		};
+	}
+
+	return {
+		result: {
+			success: true,
+			project_id,
+			agent_type,
+			message: `Setup confirmed for ${agent_type} agent. You will no longer receive setup instructions for this project.`,
+		},
+	};
+};
+
+/**
+ * Session handlers registry
+ */
+export const sessionHandlers: HandlerRegistry = {
+	start_work_session: startWorkSession,
+	heartbeat: heartbeat,
+	end_work_session: endWorkSession,
+	get_help: getHelp,
+	get_token_usage: getTokenUsage,
+	report_token_usage: reportTokenUsage,
+	confirm_agent_setup: confirmAgentSetup,
+};