@vibescope/mcp-server 0.2.9 → 0.3.1

package/src/handlers/session.ts

@@ -1,730 +1,839 @@
-/**
- * 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';
-import { getFallbackHelpContent, getAvailableHelpTopics } from '../templates/help-content.js';
-
-// Auto-detect machine hostname for worktree tracking
-const MACHINE_HOSTNAME = os.hostname();
-
-const VALID_MODES = ['lite', 'full'] as const;
-// Model, role, and agent_type are now open-ended - any string is accepted
-
-type SessionMode = typeof VALID_MODES[number];
-type SessionModel = string; // Open-ended - any model name accepted
-type SessionRole = string; // Open-ended - any role name accepted
-type AgentType = string; // Open-ended - any agent type accepted
-
-// 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 }, // Open-ended - any model name accepted
-	role: { type: 'string' as const, default: 'developer' }, // Open-ended - any role name accepted
-	hostname: { type: 'string' as const }, // Machine hostname for worktree tracking
-	agent_type: { type: 'string' as const }, // Open-ended - any agent type accepted
-};
-
-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
-	// Model is now open-ended - use as-is (normalize Claude model names for consistency)
-	const normalizedModel = model ? model.toLowerCase().replace(/^claude[- ]*/i, '') : null;
-
-	updateSession({
-		tokenUsage: {
-			callCount: 0,
-			totalTokens: 0,
-			byTool: {},
-			byModel: {},
-			currentModel: normalizedModel,
-		},
-	});
-
-	// 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);
-
-	// Try database content first
-	if (response.ok && response.data?.content) {
-		return { result: { topic, content: response.data.content } };
-	}
-
-	// Fall back to local content if database is empty or unavailable
-	const fallback = getFallbackHelpContent(topic);
-	if (fallback) {
-		return { result: { topic, content: fallback.content } };
-	}
-
-	// Topic not found in either source - show available topics
-	const available = getAvailableHelpTopics();
-
-	return {
-		result: {
-			error: `Unknown topic: ${topic}`,
-			available,
-		},
-	};
-};
-
-// 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 }, // Open-ended - any model name accepted
-};
-
-const confirmAgentSetupSchema = {
-	project_id: { type: 'string' as const, required: true as const },
-	agent_type: { type: 'string' as const, required: true as const }, // Open-ended - any agent type accepted
-};
-
-/**
- * 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);
-
-	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,
-};
+/**
+ * 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';
+import { getFallbackHelpContent, getAvailableHelpTopics } from '../templates/help-content.js';
+import { normalizeGitUrl } from '../utils.js';
+
+// Auto-detect machine hostname for worktree tracking
+const MACHINE_HOSTNAME = os.hostname();
+
+const VALID_MODES = ['lite', 'full'] as const;
+// Model, role, and agent_type are now open-ended - any string is accepted
+
+type SessionMode = typeof VALID_MODES[number];
+type SessionModel = string; // Open-ended - any model name accepted
+type SessionRole = string; // Open-ended - any role name accepted
+type AgentType = string; // Open-ended - any agent type accepted
+
+// 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 }, // Open-ended - any model name accepted
+	role: { type: 'string' as const, default: 'developer' }, // Open-ended - any role name accepted
+	hostname: { type: 'string' as const }, // Machine hostname for worktree tracking
+	agent_type: { type: 'string' as const }, // Open-ended - any agent type accepted
+};
+
+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;
+
+	// Normalize git_url and track if it was changed - helps agents understand URL matching
+	const normalizedGitUrl = git_url ? normalizeGitUrl(git_url) : null;
+	const gitUrlWasNormalized = git_url && normalizedGitUrl && git_url !== normalizedGitUrl;
+
+	const { session, updateSession } = ctx;
+
+	// Reset token tracking for new session with model info
+	// Model is now open-ended - use as-is (normalize Claude model names for consistency)
+	const normalizedModel = model ? model.toLowerCase().replace(/^claude[- ]*/i, '') : null;
+
+	updateSession({
+		tokenUsage: {
+			callCount: 0,
+			totalTokens: 0,
+			byTool: {},
+			byModel: {},
+			currentModel: normalizedModel,
+		},
+	});
+
+	// 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;
+
+	// Inform agent if git_url was normalized (helps explain URL matching behavior)
+	if (gitUrlWasNormalized) {
+		result.git_url_normalized = {
+			message: 'Your git URL was normalized for project lookup. All URL formats for the same repository resolve to the same project.',
+			original: git_url,
+			normalized: normalizedGitUrl,
+			examples: [
+				'git@github.com:owner/repo.git → https://github.com/owner/repo',
+				'https://GITHUB.COM/Owner/Repo/ → https://github.com/owner/repo',
+				'http://github.com/owner/repo.git → https://github.com/owner/repo',
+			],
+		};
+	}
+
+	// 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 FIRST_TIME_CONNECTION guidance for git-flow
+			if (data.project.git_workflow === 'git-flow') {
+				result.FIRST_TIME_CONNECTION = {
+					workflow: 'git-flow',
+					steps: [
+						`1. git checkout ${data.project.git_develop_branch || 'develop'}`,
+						`2. git pull origin ${data.project.git_develop_branch || 'develop'}`,
+						'3. All feature branches must be created from develop',
+					],
+					warning: 'Working from main or stale branches causes merge conflicts.',
+					base_branch: data.project.git_develop_branch || 'develop',
+				};
+			} else if (data.project.git_workflow === 'github-flow') {
+				result.FIRST_TIME_CONNECTION = {
+					workflow: 'github-flow',
+					steps: [
+						`1. git checkout ${data.project.git_main_branch || 'main'}`,
+						`2. git pull origin ${data.project.git_main_branch || 'main'}`,
+						'3. All feature branches must be created from main',
+					],
+					warning: 'Working from stale branches causes merge conflicts.',
+					base_branch: data.project.git_main_branch || 'main',
+				};
+			}
+		}
+	}
+
+	// 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);
+
+	// Try database content first
+	if (response.ok && response.data?.content) {
+		return { result: { topic, content: response.data.content } };
+	}
+
+	// Fall back to local content if database is empty or unavailable
+	const fallback = getFallbackHelpContent(topic);
+	if (fallback) {
+		return { result: { topic, content: fallback.content } };
+	}
+
+	// Topic not found in either source - show available topics
+	const available = getAvailableHelpTopics();
+
+	return {
+		result: {
+			error: `Unknown topic: ${topic}`,
+			available,
+		},
+	};
+};
+
+// 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 }, // Open-ended - any model name accepted
+};
+
+const confirmAgentSetupSchema = {
+	project_id: { type: 'string' as const, required: true as const },
+	agent_type: { type: 'string' as const, required: true as const }, // Open-ended - any agent type accepted
+};
+
+/**
+ * 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);
+
+	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.`,
+		},
+	};
+};
+
+const signalIdleSchema = {
+	session_id: { type: 'string' as const },
+};
+
+/**
+ * Signal that the agent is idle (no more tasks to work on).
+ * This immediately updates the session status to 'idle', providing real-time
+ * visibility on the dashboard instead of waiting for heartbeat timeout.
+ *
+ * Call this when:
+ * - complete_task returns no next_task
+ * - get_next_task returns no tasks
+ * - There's genuinely no work to do
+ */
+export const signalIdle: Handler = async (args, ctx) => {
+	const { session_id } = parseArgs(args, signalIdleSchema);
+	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();
+	const response = await apiClient.signalIdle(targetSession);
+
+	if (!response.ok) {
+		return {
+			result: {
+				error: response.error || 'Failed to signal idle',
+			},
+		};
+	}
+
+	return {
+		result: {
+			success: true,
+			session_id: targetSession,
+			status: 'idle',
+			message: 'Session marked as idle. Dashboard will show you as inactive until you start a new task.',
+			next_steps: [
+				'Wait for new tasks to be added by the user',
+				'Or call start_fallback_activity() to do background work',
+				'Or call end_work_session() if you are done for the session',
+			],
+			AUTONOMY_RULES: {
+				message: 'Agents must be autonomous. Follow these rules:',
+				rules: [
+					'Never ask "should I continue?" → Just continue',
+					'Never ask "should I clear context?" → Just clear it',
+					'Never say "let me know what to do" → Use get_next_task or fallback activities',
+					'When context grows large: /clear → start_work_session (don\'t ask, just do it)',
+				],
+				preferred_activities: ['code_review', 'security_review', 'test_coverage', 'documentation_review', 'dependency_audit'],
+				directive: 'BE PROACTIVE: Start a fallback activity now rather than waiting for user input.',
+			},
+		},
+	};
+};
+
+/**
+ * Session handlers registry
+ */
+export const sessionHandlers: HandlerRegistry = {
+	start_work_session: startWorkSession,
+	heartbeat: heartbeat,
+	end_work_session: endWorkSession,
+	signal_idle: signalIdle,
+	get_help: getHelp,
+	get_token_usage: getTokenUsage,
+	report_token_usage: reportTokenUsage,
+	confirm_agent_setup: confirmAgentSetup,
+};