@vibescope/mcp-server 0.0.1

package/src/handlers/session.ts

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