@anastops/mcp-server 1.1.2 → 2.0.0

package/dist/handlers/v3/session-tools.js

@@ -0,0 +1,716 @@
+/**
+ * MCP v3.0 Session Management Tools
+ * Consolidated session management following aggressive consolidation plan
+ *
+ * Tools:
+ * - session_manage: Create, fork, archive, delete operations
+ * - session_query: Status, list, report query operations
+ * - session_queue_config: Configure and query queue settings
+ *
+ * @see docs/MCP-V3-AGGRESSIVE-CONSOLIDATION.md
+ */
+import { SessionManager, SessionForkService, addBreadcrumb, } from '@anastops/core';
+import { getPersistence } from '../../persistence.js';
+import { safePersist, formatSessionReport, tasks, agents, artifacts } from '../handlers.base.js';
+// Shared instances
+const sessionManager = new SessionManager();
+const forkService = new SessionForkService(sessionManager);
+// ============================================================================
+// TOOL SCHEMAS
+// ============================================================================
+/**
+ * session_manage tool schema
+ *
+ * Handles create, fork, archive, and delete operations on sessions.
+ *
+ * @example Create a new session
+ * ```typescript
+ * session_manage({
+ *   operation: 'create',
+ *   objective: 'Build authentication system',
+ *   concurrency: 3,
+ *   auto_execute: true
+ * })
+ * ```
+ *
+ * @example Fork a session
+ * ```typescript
+ * session_manage({
+ *   operation: 'fork',
+ *   session_id: 'abc123',
+ *   reason: 'Explore OAuth approach'
+ * })
+ * ```
+ *
+ * @example Archive a session
+ * ```typescript
+ * session_manage({
+ *   operation: 'archive',
+ *   session_id: 'abc123'
+ * })
+ * ```
+ *
+ * @example Delete a session
+ * ```typescript
+ * session_manage({
+ *   operation: 'delete',
+ *   session_id: 'abc123',
+ *   confirm: true
+ * })
+ * ```
+ */
+export const sessionManageSchema = {
+    name: 'session_manage',
+    description: 'Manage sessions: create new sessions, fork existing sessions, archive completed sessions, or delete sessions permanently',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            operation: {
+                type: 'string',
+                enum: ['create', 'fork', 'archive', 'delete'],
+                description: 'Operation to perform: create=spawn new session, fork=create alternative branch, archive=mark completed, delete=permanently remove',
+            },
+            // CREATE operation parameters
+            objective: {
+                type: 'string',
+                description: 'Required for create: High-level objective for the session',
+            },
+            context_files: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'For create: Array of file paths to include in session context',
+            },
+            parent_session: {
+                type: 'string',
+                description: 'For create: Parent session ID if this is a child session',
+            },
+            concurrency: {
+                type: 'number',
+                description: 'For create: Max concurrent running tasks (1-10, default: 1)',
+            },
+            auto_execute: {
+                type: 'boolean',
+                description: 'For create: Auto-execute queued tasks when slots available (default: false)',
+            },
+            // FORK operation parameters
+            session_id: {
+                type: 'string',
+                description: 'Required for fork/archive/delete: Session ID to operate on',
+            },
+            fork_point: {
+                type: 'number',
+                description: 'For fork: Task number to fork from (optional)',
+            },
+            reason: {
+                type: 'string',
+                description: 'For fork: Reason for forking (e.g., "Explore OAuth approach")',
+            },
+            // DELETE operation parameters
+            session_ids: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'For delete: Array of session IDs to delete (bulk deletion)',
+            },
+            status: {
+                type: 'string',
+                enum: ['active', 'completed', 'archived'],
+                description: 'For delete: Delete all sessions with this status',
+            },
+            older_than_days: {
+                type: 'number',
+                description: 'For delete: Delete sessions older than N days',
+            },
+            confirm: {
+                type: 'boolean',
+                description: 'Required for delete: Must be true to execute deletion (safety check)',
+            },
+        },
+        required: ['operation'],
+    },
+};
+/**
+ * session_query tool schema
+ *
+ * Queries session information: get status, list sessions, or generate reports.
+ *
+ * @example Get session status
+ * ```typescript
+ * session_query({
+ *   operation: 'status',
+ *   session_id: 'abc123'
+ * })
+ * ```
+ *
+ * @example List active sessions
+ * ```typescript
+ * session_query({
+ *   operation: 'list',
+ *   status_filter: 'active',
+ *   format: 'table'
+ * })
+ * ```
+ *
+ * @example Generate session report
+ * ```typescript
+ * session_query({
+ *   operation: 'report',
+ *   session_id: 'abc123',
+ *   include_output: true,
+ *   include_artifacts: false
+ * })
+ * ```
+ */
+export const sessionQuerySchema = {
+    name: 'session_query',
+    description: 'Query session information: get status for a specific session, list all sessions with filters, or generate comprehensive reports',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            operation: {
+                type: 'string',
+                enum: ['status', 'list', 'report'],
+                description: 'Type of query: status=get session details, list=list sessions with filters, report=generate comprehensive report',
+            },
+            // STATUS operation parameters
+            session_id: {
+                type: 'string',
+                description: 'Required for status: Session ID to query. Optional for report: omit to get all sessions',
+            },
+            // LIST operation parameters
+            status_filter: {
+                type: 'string',
+                enum: ['active', 'completed', 'archived'],
+                description: 'For list/report: Filter sessions by status',
+            },
+            include_forks: {
+                type: 'boolean',
+                description: 'For list: Include forked sessions in results (default: false)',
+            },
+            limit: {
+                type: 'number',
+                description: 'For list/report: Maximum number of sessions to return (default: 20 for report)',
+            },
+            format: {
+                type: 'string',
+                enum: ['table', 'json'],
+                description: 'For list: Output format (table=ASCII table, json=raw JSON, default: json)',
+            },
+            // REPORT operation parameters
+            include_output: {
+                type: 'boolean',
+                description: 'For report: Include full task output content (default: true)',
+            },
+            include_artifacts: {
+                type: 'boolean',
+                description: 'For report: Include artifact content, not just metadata (default: false)',
+            },
+        },
+        required: ['operation'],
+    },
+};
+/**
+ * session_queue_config tool schema
+ *
+ * Configure queue settings or query queue status for a session.
+ *
+ * @example Configure queue settings
+ * ```typescript
+ * session_queue_config({
+ *   operation: 'configure',
+ *   session_id: 'abc123',
+ *   concurrency: 5,
+ *   auto_execute: true
+ * })
+ * ```
+ *
+ * @example Query queue status
+ * ```typescript
+ * session_queue_config({
+ *   operation: 'status',
+ *   session_id: 'abc123'
+ * })
+ * ```
+ */
+export const sessionQueueConfigSchema = {
+    name: 'session_queue_config',
+    description: 'Configure session queue settings (concurrency, auto-execution) or query queue status (running/queued counts, available slots)',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            operation: {
+                type: 'string',
+                enum: ['configure', 'status'],
+                description: 'Operation: configure=update queue settings, status=get queue status and ready tasks',
+            },
+            session_id: {
+                type: 'string',
+                description: 'Required: Session ID to configure or query',
+            },
+            // CONFIGURE operation parameters
+            concurrency: {
+                type: 'number',
+                description: 'For configure: Max concurrent running tasks (1-10)',
+            },
+            auto_execute: {
+                type: 'boolean',
+                description: 'For configure: Auto-execute queued tasks when slots available',
+            },
+        },
+        required: ['operation', 'session_id'],
+    },
+};
+// ============================================================================
+// HANDLER IMPLEMENTATIONS
+// ============================================================================
+/**
+ * Validates operation-specific required fields
+ * Throws error if required fields are missing for the operation
+ */
+function validateSessionManageArgs(operation, args) {
+    switch (operation) {
+        case 'create':
+            if (typeof args['objective'] !== 'string' || args['objective'] === '') {
+                throw new Error('operation=create requires: objective (string)');
+            }
+            break;
+        case 'fork':
+            if (typeof args['session_id'] !== 'string' || args['session_id'] === '') {
+                throw new Error('operation=fork requires: session_id (string)');
+            }
+            break;
+        case 'archive':
+            if (typeof args['session_id'] !== 'string' || args['session_id'] === '') {
+                throw new Error('operation=archive requires: session_id (string)');
+            }
+            break;
+        case 'delete': {
+            if (args['confirm'] !== true) {
+                throw new Error('operation=delete requires: confirm=true (safety check)');
+            }
+            // Must provide at least one filter: session_id, session_ids, status, or older_than_days
+            const hasFilter = (typeof args['session_id'] === 'string' && args['session_id'] !== '') ||
+                (Array.isArray(args['session_ids']) && args['session_ids'].length > 0) ||
+                (typeof args['status'] === 'string' && args['status'] !== '') ||
+                typeof args['older_than_days'] === 'number';
+            if (!hasFilter) {
+                throw new Error('operation=delete requires at least one filter: session_id, session_ids, status, or older_than_days');
+            }
+            break;
+        }
+        default:
+            throw new Error(`Unknown operation: ${operation}`);
+    }
+}
+function validateSessionQueryArgs(operation, args) {
+    switch (operation) {
+        case 'status':
+            if (typeof args['session_id'] !== 'string' || args['session_id'] === '') {
+                throw new Error('operation=status requires: session_id (string)');
+            }
+            break;
+        case 'list':
+            // No required fields for list - all optional
+            break;
+        case 'report':
+            // session_id is optional for report (omit to get all sessions)
+            break;
+        default:
+            throw new Error(`Unknown operation: ${operation}`);
+    }
+}
+function validateQueueConfigArgs(operation, args) {
+    // session_id is always required (enforced in schema)
+    if (typeof args['session_id'] !== 'string' || args['session_id'] === '') {
+        throw new Error('session_id (string) is required');
+    }
+    switch (operation) {
+        case 'configure':
+            // Validate concurrency if provided
+            if (args['concurrency'] !== undefined) {
+                const concurrency = args['concurrency'];
+                if (concurrency < 1 || concurrency > 10) {
+                    throw new Error('concurrency must be between 1 and 10');
+                }
+            }
+            break;
+        case 'status':
+            // No additional validation needed
+            break;
+        default:
+            throw new Error(`Unknown operation: ${operation}`);
+    }
+}
+/**
+ * session_manage handler
+ * Routes to appropriate handler based on operation parameter
+ */
+export async function handleSessionManage(args) {
+    const operation = args['operation'];
+    // Validate operation-specific required fields
+    validateSessionManageArgs(operation, args);
+    switch (operation) {
+        case 'create':
+            return handleSessionCreate(args);
+        case 'fork':
+            return handleSessionFork(args);
+        case 'archive':
+            return handleSessionArchive(args);
+        case 'delete':
+            return handleSessionDelete(args);
+        default:
+            throw new Error(`Unknown operation: ${operation}`);
+    }
+}
+/**
+ * session_query handler
+ * Routes to appropriate handler based on operation parameter
+ */
+export async function handleSessionQuery(args) {
+    const operation = args['operation'];
+    // Validate operation-specific required fields
+    validateSessionQueryArgs(operation, args);
+    switch (operation) {
+        case 'status':
+            return handleSessionStatus(args);
+        case 'list':
+            return handleSessionList(args);
+        case 'report':
+            return handleSessionReport(args);
+        default:
+            throw new Error(`Unknown operation: ${operation}`);
+    }
+}
+/**
+ * session_queue_config handler
+ * Routes to configure or status operation
+ */
+export async function handleSessionQueueConfig(args) {
+    const operation = args['operation'];
+    // Validate operation-specific required fields
+    validateQueueConfigArgs(operation, args);
+    switch (operation) {
+        case 'configure':
+            return handleQueueConfigure(args);
+        case 'status':
+            return handleQueueStatus(args);
+        default:
+            throw new Error(`Unknown operation: ${operation}`);
+    }
+}
+// ============================================================================
+// OPERATION IMPLEMENTATIONS
+// ============================================================================
+/**
+ * Create a new session
+ */
+function handleSessionCreate(args) {
+    const objective = args['objective'];
+    addBreadcrumb('Creating session', { objective }, 'info', 'session');
+    const session = sessionManager.spawn({
+        objective,
+        ...(args['context_files'] !== undefined && {
+            context_files: args['context_files'],
+        }),
+        ...(args['parent_session'] !== undefined && {
+            parent_session: args['parent_session'],
+        }),
+        ...(args['concurrency'] !== undefined && {
+            concurrency: args['concurrency'],
+        }),
+        ...(args['auto_execute'] !== undefined && {
+            auto_execute: args['auto_execute'],
+        }),
+    });
+    addBreadcrumb('Session created', { session_id: session.id }, 'info', 'session');
+    // Persist to MongoDB
+    safePersist(getPersistence().saveSession(session));
+    return Promise.resolve({
+        session_id: session.id,
+        objective: session.objective,
+        status: session.status,
+        queue_config: session.queue_config,
+    });
+}
+/**
+ * Fork an existing session
+ */
+function handleSessionFork(args) {
+    const sessionId = args['session_id'];
+    const reason = args['reason'] ?? 'unknown';
+    addBreadcrumb('Forking session', { session_id: sessionId, reason }, 'info', 'session');
+    const forked = forkService.fork({
+        session_id: sessionId,
+        ...(args['fork_point'] !== undefined && {
+            fork_point: args['fork_point'],
+        }),
+        ...(args['reason'] !== undefined && { reason }),
+    });
+    addBreadcrumb('Session forked', { forked_session_id: forked.id, parent_id: forked.parent_session_id }, 'info', 'session');
+    // Persist to MongoDB
+    safePersist(getPersistence().saveSession(forked));
+    return Promise.resolve({
+        forked_session_id: forked.id,
+        parent_id: forked.parent_session_id,
+        fork_point: forked.fork_point,
+    });
+}
+/**
+ * Archive a session
+ */
+function handleSessionArchive(args) {
+    const sessionId = args['session_id'];
+    const session = sessionManager.updateStatus(sessionId, 'archived');
+    // Persist to MongoDB
+    safePersist(getPersistence().saveSession(session));
+    return Promise.resolve({
+        session_id: session.id,
+        status: session.status,
+    });
+}
+/**
+ * Delete session(s) permanently
+ */
+async function handleSessionDelete(args) {
+    const sessionId = args['session_id'];
+    const sessionIds = args['session_ids'];
+    const statusFilter = args['status'];
+    const olderThanDays = args['older_than_days'];
+    const persistence = getPersistence();
+    // Single session deletion
+    if (sessionId !== undefined && sessionId !== '') {
+        // Remove from in-memory cache
+        sessionManager.remove(sessionId);
+        // Remove related tasks from cache
+        for (const [taskId, task] of tasks.entries()) {
+            if (task.session_id === sessionId) {
+                tasks.delete(taskId);
+            }
+        }
+        // Remove related agents from cache
+        for (const [agentId, agent] of agents.entries()) {
+            if (agent.session_id === sessionId) {
+                agents.delete(agentId);
+            }
+        }
+        // Remove related artifacts from cache
+        for (const [artifactId, artifact] of artifacts.entries()) {
+            if (artifact.session_id === sessionId) {
+                artifacts.delete(artifactId);
+            }
+        }
+        const deleted = await persistence.deleteSession(sessionId);
+        return { deleted: deleted, session_id: sessionId };
+    }
+    // Build filters for bulk deletion
+    const filters = {};
+    if (sessionIds !== undefined && sessionIds.length > 0) {
+        filters.session_ids = sessionIds;
+    }
+    if (statusFilter !== undefined && statusFilter !== '') {
+        filters.status = statusFilter;
+    }
+    if (olderThanDays !== undefined) {
+        const cutoffDate = new Date();
+        cutoffDate.setDate(cutoffDate.getDate() - olderThanDays);
+        filters.older_than = cutoffDate;
+    }
+    const result = await persistence.deleteSessions(filters);
+    // Clean up in-memory caches for deleted sessions
+    for (const deletedId of result.session_ids) {
+        sessionManager.remove(deletedId);
+        for (const [taskId, task] of tasks.entries()) {
+            if (task.session_id === deletedId) {
+                tasks.delete(taskId);
+            }
+        }
+        for (const [agentId, agent] of agents.entries()) {
+            if (agent.session_id === deletedId) {
+                agents.delete(agentId);
+            }
+        }
+        for (const [artifactId, artifact] of artifacts.entries()) {
+            if (artifact.session_id === deletedId) {
+                artifacts.delete(artifactId);
+            }
+        }
+    }
+    return {
+        deleted_count: result.deleted_count,
+        session_ids: result.session_ids,
+    };
+}
+/**
+ * Get session status
+ */
+function handleSessionStatus(args) {
+    const sessionId = args['session_id'];
+    const status = sessionManager.getStatus(sessionId);
+    // TOON encoding applied in handleToolCall
+    return Promise.resolve(status);
+}
+/**
+ * List sessions with filters
+ */
+async function handleSessionList(args) {
+    // Get from in-memory first
+    const inMemorySessions = sessionManager.list({
+        ...(args['status_filter'] !== undefined && {
+            status: args['status_filter'],
+        }),
+        ...(args['include_forks'] !== undefined && {
+            include_forks: args['include_forks'],
+        }),
+        ...(args['limit'] !== undefined && {
+            limit: args['limit'],
+        }),
+    });
+    // Also get from MongoDB for persistence
+    const persistedSessions = await getPersistence().listSessions({
+        ...(args['status_filter'] !== undefined && {
+            status: args['status_filter'],
+        }),
+        ...(args['limit'] !== undefined && {
+            limit: args['limit'],
+        }),
+    });
+    // Merge: in-memory takes precedence, then add persisted ones not in memory
+    const inMemoryIds = new Set(inMemorySessions.map((s) => s.id));
+    const sessions = [
+        ...inMemorySessions,
+        ...persistedSessions.filter((s) => !inMemoryIds.has(s.id)),
+    ];
+    // Return raw result for table formatting to be applied in handleToolCall
+    const result = {
+        count: sessions.length,
+        sessions: sessions.map((s) => ({
+            id: s.id,
+            objective: s.objective,
+            status: s.status,
+            created_at: s.created_at,
+        })),
+    };
+    // Don't apply TOON encoding here - let handleToolCall handle formatting
+    return result;
+}
+/**
+ * Generate session report
+ */
+async function handleSessionReport(args) {
+    const sessionId = args['session_id'];
+    const statusFilter = args['status_filter'];
+    const includeOutput = args['include_output'] ?? true;
+    const includeArtifactContent = args['include_artifacts'] ?? false;
+    const limit = args['limit'] ?? 20;
+    const persistence = getPersistence();
+    if (sessionId !== undefined && sessionId !== '') {
+        // Single session report
+        const report = await persistence.getSessionReport(sessionId);
+        if (report === null) {
+            throw new Error(`Session not found: ${sessionId}`);
+        }
+        return formatSessionReport(report, includeOutput, includeArtifactContent);
+    }
+    // All sessions report
+    const reportFilters = { limit };
+    if (statusFilter !== undefined) {
+        reportFilters.status = statusFilter;
+    }
+    const reports = await persistence.getAllSessionReports(reportFilters);
+    return {
+        total_sessions: reports.length,
+        sessions: reports.map((r) => formatSessionReport(r, includeOutput, includeArtifactContent)),
+    };
+}
+/**
+ * Configure queue settings
+ */
+function handleQueueConfigure(args) {
+    const sessionId = args['session_id'];
+    const concurrency = args['concurrency'];
+    const autoExecute = args['auto_execute'];
+    // Build updates object
+    const updates = {};
+    if (concurrency !== undefined) {
+        updates.concurrency = concurrency;
+    }
+    if (autoExecute !== undefined) {
+        updates.auto_execute = autoExecute;
+    }
+    if (Object.keys(updates).length === 0) {
+        // No updates provided, just return current config
+        const session = sessionManager.getSession(sessionId);
+        return Promise.resolve({
+            session_id: sessionId,
+            queue_config: session.queue_config,
+        });
+    }
+    // Update queue config
+    const session = sessionManager.updateQueueConfig(sessionId, updates);
+    safePersist(getPersistence().saveSession(session));
+    return Promise.resolve({
+        session_id: sessionId,
+        queue_config: session.queue_config,
+        updated: true,
+    });
+}
+/**
+ * Get queue status
+ */
+async function handleQueueStatus(args) {
+    const sessionId = args['session_id'];
+    const session = sessionManager.getSession(sessionId);
+    // Get tasks for the session
+    const sessionTasks = [];
+    for (const [, task] of tasks.entries()) {
+        if (task.session_id === sessionId) {
+            sessionTasks.push(task);
+        }
+    }
+    // Also get from MongoDB
+    const persistedTasks = await getPersistence().listTasks({ session_id: sessionId });
+    const inMemoryIds = new Set(sessionTasks.map((t) => t.id));
+    const allTasks = [...sessionTasks, ...persistedTasks.filter((t) => !inMemoryIds.has(t.id))];
+    // Count by status
+    const runningCount = allTasks.filter((t) => t.status === 'running').length;
+    const queuedCount = allTasks.filter((t) => t.status === 'queued').length;
+    const pendingCount = allTasks.filter((t) => t.status === 'pending').length;
+    const completedCount = allTasks.filter((t) => t.status === 'completed').length;
+    const failedCount = allTasks.filter((t) => t.status === 'failed').length;
+    const availableSlots = Math.max(0, session.queue_config.concurrency - runningCount);
+    // Find ready tasks (queued with met dependencies)
+    const queuedTasks = allTasks.filter((t) => t.status === 'queued');
+    const taskMap = new Map(allTasks.map((t) => [t.id, t]));
+    const readyTasks = queuedTasks
+        .filter((task) => {
+        if (task.dependencies.length === 0)
+            return true;
+        return task.dependencies.every((depId) => {
+            const depTask = taskMap.get(depId);
+            return depTask !== undefined && depTask.status === 'completed';
+        });
+    })
+        .sort((a, b) => {
+        // Sort by priority (higher first), then by created_at (earlier first)
+        if (a.priority !== b.priority)
+            return b.priority - a.priority;
+        return a.created_at.getTime() - b.created_at.getTime();
+    })
+        .slice(0, availableSlots)
+        .map((t) => t.id);
+    return {
+        session_id: sessionId,
+        queue_config: session.queue_config,
+        running_count: runningCount,
+        queued_count: queuedCount,
+        pending_count: pendingCount,
+        completed_count: completedCount,
+        failed_count: failedCount,
+        available_slots: availableSlots,
+        ready_tasks: readyTasks,
+    };
+}
+// ============================================================================
+// EXPORTS
+// ============================================================================
+export { sessionManager, forkService };
+//# sourceMappingURL=session-tools.js.map