@magic-ingredients/tiny-brain-local 0.3.10

package/dist/tools/plan/plan.tool.js

@@ -0,0 +1,643 @@
+import { z } from 'zod';
+import { createSuccessResult, createErrorResult } from '../index.js';
+import { PlanningService } from '@magic-ingredients/tiny-brain-core';
+import { PlanWatcherService } from '../../services/plan-watcher.service.js';
+const PlanArgsSchema = z.object({
+    operation: z.enum(['accept', 'update', 'status', 'report', 'list', 'archive', 'switch', 'watch', 'stop-watch']),
+    // For 'accept' operation
+    planName: z.string().optional(),
+    planDetails: z.string().optional(),
+    // For 'update' operation
+    planId: z.string().optional(),
+    updates: z
+        .object({
+        overview: z.string().optional(),
+        updateBlockers: z
+            .array(z.object({
+            description: z.string(),
+            severity: z.enum(['low', 'medium', 'high']),
+            todoId: z.string().optional(),
+        }))
+            .optional(),
+        addPhase: z
+            .object({
+            title: z.string(),
+            description: z.string(),
+        })
+            .optional(),
+        updatePhase: z
+            .object({
+            phaseNumber: z.number(),
+            status: z.enum(['pending', 'in_progress', 'completed']).optional(),
+            addTodo: z.string().optional(),
+            completeTodo: z.string().optional(),
+            // Bulk operations
+            addTodos: z.array(z.string()).optional(),
+            completeTodos: z.array(z.string()).optional(),
+        })
+            .optional(),
+        // Support for updating multiple phases
+        updatePhases: z
+            .array(z.object({
+            phaseNumber: z.number(),
+            status: z.enum(['pending', 'in_progress', 'completed']).optional(),
+            addTodo: z.string().optional(),
+            completeTodo: z.string().optional(),
+            // Bulk operations
+            addTodos: z.array(z.string()).optional(),
+            completeTodos: z.array(z.string()).optional(),
+        }))
+            .optional(),
+    })
+        .optional(),
+    // For 'status' operation
+    verbose: z.boolean().optional(),
+    // For 'report' operation
+    saveToFile: z.boolean().optional(),
+    // For 'list' operation
+    listStatus: z.enum(['active', 'completed', 'archived', 'all']).optional(),
+    // For 'archive' operation
+    reason: z.string().optional(),
+    // For 'switch' operation
+    // planId is reused from update operation
+    // Note: switchToPlan automatically unarchives if needed
+    // For 'watch' operation
+    port: z.number().optional().default(8765),
+    autoOpen: z.boolean().optional().default(true),
+    showAll: z.boolean().optional().default(false),
+});
+// Singleton watcher instance
+let watcherInstance = null;
+// For testing - clear the singleton
+export function clearWatcherInstance() {
+    watcherInstance = null;
+}
+export class PlanTool {
+    static getToolDefinition() {
+        return {
+            name: 'plan',
+            description: `📋 LIVING DOCUMENT PLANNER 📋
+
+⚡ COLLABORATIVE PLANNING: Captures user-AI planning discussions and creates structured, trackable plans.
+
+✅ OPERATIONS:
+  • accept: Create plan from collaborative discussion (planName + planDetails)
+  • update: Add phases, todos, or update status (usually automatic)
+  • status: Show current plan progress and summary
+  • report: Generate and display comprehensive markdown report
+  • list: List all plans (active, completed, archived)
+  • archive: Archive a completed plan
+  • switch: Switch to a different plan (automatically unarchives if needed)
+  • watch: Launch web dashboard to monitor plans in real-time
+  • stop-watch: Stop the running plan watcher dashboard
+
+💡 WORKFLOW:
+  1. User & AI collaborate on planning in chat
+  2. AI invokes 'accept' with planName + full planning discussion
+  3. Tool extracts phases, todos, and structure automatically
+  4. Creates persona-specific JSON plan document
+  5. Tracks updates and progress across conversations
+
+🎯 FEATURES:
+  • Automatic extraction of phases and todos from discussions
+  • Smart parsing of collaborative planning conversations
+  • Cross-chat plan continuity and progress tracking
+  • Living documents that evolve with your project
+
+📝 UPDATE BEST PRACTICES:
+  • After accepting a plan, use the returned JSON structure to make precise updates
+  • Match todo content exactly as shown in the structure
+  • Update phases based on actual progress made
+  • Complete todos by referencing their exact content from the plan structure
+  • Use bulk operations to update multiple items at once:
+    - completeTodos: ["todo1", "todo2"] to complete multiple todos
+    - addTodos: ["task1", "task2"] to add multiple todos
+    - updatePhases: [{...}, {...}] to update multiple phases`,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    operation: {
+                        type: 'string',
+                        enum: ['accept', 'update', 'status', 'report', 'list', 'archive', 'switch', 'watch', 'stop-watch'],
+                        description: 'The planning operation to perform',
+                    },
+                    // For 'accept' operation
+                    planName: {
+                        type: 'string',
+                        description: 'Name/title for the new plan (required for accept)',
+                    },
+                    planDetails: {
+                        type: 'string',
+                        description: 'Large chunk of text containing the collaborative planning discussion between user and AI (required for accept)',
+                    },
+                    // For 'update' operation
+                    planId: {
+                        type: 'string',
+                        description: 'Plan ID to update (optional, uses current active if not provided)',
+                    },
+                    updates: {
+                        type: 'object',
+                        properties: {
+                            overview: { type: 'string' },
+                            updateBlockers: {
+                                type: 'array',
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        description: { type: 'string' },
+                                        severity: { type: 'string', enum: ['low', 'medium', 'high'] },
+                                        todoId: { type: 'string' },
+                                    },
+                                    required: ['description', 'severity'],
+                                },
+                            },
+                            addPhase: {
+                                type: 'object',
+                                properties: {
+                                    title: { type: 'string' },
+                                    description: { type: 'string' },
+                                },
+                            },
+                            updatePhase: {
+                                type: 'object',
+                                properties: {
+                                    phaseNumber: { type: 'number' },
+                                    status: { type: 'string', enum: ['pending', 'in_progress', 'completed'] },
+                                    addTodo: { type: 'string' },
+                                    completeTodo: { type: 'string' },
+                                },
+                            },
+                        },
+                        description: 'Updates to apply to the plan. Use exact todo content from plan structure for completeTodo. Update phases based on actual work completed.',
+                    },
+                    // For 'status' operation
+                    verbose: {
+                        type: 'boolean',
+                        description: 'Show detailed todo lists in status',
+                    },
+                    // For 'report' operation
+                    saveToFile: {
+                        type: 'boolean',
+                        description: 'Save markdown report to file (optional for report)',
+                    },
+                    // For 'list' operation
+                    listStatus: {
+                        type: 'string',
+                        enum: ['active', 'completed', 'archived', 'all'],
+                        description: 'Filter plans by status',
+                    },
+                    // For 'archive' operation
+                    reason: {
+                        type: 'string',
+                        description: 'Reason for archiving',
+                    },
+                    // For 'switch' operation
+                    // planId is reused from update operation
+                    force: {
+                        type: 'boolean',
+                        description: 'Force switch to archived plans (optional)',
+                    },
+                    // For 'watch' operation
+                    port: {
+                        type: 'number',
+                        description: 'Port number for the dashboard (default: 8765)',
+                    },
+                    autoOpen: {
+                        type: 'boolean',
+                        description: 'Auto-open browser when dashboard starts',
+                    },
+                    showAll: {
+                        type: 'boolean',
+                        description: 'Show all plans including archived (default: false)',
+                    },
+                },
+                required: ['operation'],
+            },
+        };
+    }
+    static async execute(args, context) {
+        try {
+            const validatedArgs = PlanArgsSchema.parse(args);
+            // All plan operations except watch/stop-watch require an active persona
+            if (validatedArgs.operation !== 'watch' && validatedArgs.operation !== 'stop-watch' && !context.activePersona?.id) {
+                return createErrorResult('No active persona found. Plan operations require an active persona. Use the "as" tool to switch to a persona first.');
+            }
+            switch (validatedArgs.operation) {
+                case 'accept':
+                    return await PlanTool.handleAccept(validatedArgs, context);
+                case 'update':
+                    return await PlanTool.handleUpdate(validatedArgs, context);
+                case 'status':
+                    return await PlanTool.handleStatus(validatedArgs, context);
+                case 'report':
+                    return await PlanTool.handleReport(validatedArgs, context);
+                case 'list':
+                    return await PlanTool.handleList(validatedArgs, context);
+                case 'archive':
+                    return await PlanTool.handleArchive(validatedArgs, context);
+                case 'switch':
+                    return await PlanTool.handleSwitch(validatedArgs, context);
+                case 'watch':
+                    return await PlanTool.handleWatch(validatedArgs, context);
+                case 'stop-watch':
+                    return await PlanTool.handleStopWatch(validatedArgs, context);
+                default:
+                    return createErrorResult(`Unknown operation: ${validatedArgs.operation}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                return createErrorResult(`Invalid arguments: ${error.errors.map((e) => e.message).join(', ')}`);
+            }
+            return createErrorResult(error instanceof Error ? error.message : 'Unknown error occurred');
+        }
+    }
+    static async handleAccept(args, context) {
+        if (!args.planName || !args.planDetails) {
+            return createErrorResult('Plan name and plan details are required to accept a new plan.');
+        }
+        try {
+            // Create the plan using service
+            if (!context.activePersona) {
+                return createErrorResult('Active persona is required');
+            }
+            // Create context with plan input including planDetails for phase extraction
+            // Create service with RequestContext
+            const planningService = new PlanningService(context);
+            const plan = await planningService.createPlan({
+                title: args.planName,
+                overview: args.planDetails,
+                planDetails: args.planDetails, // Service will extract phases from this
+            });
+            // Set the new plan as active
+            const setActiveResult = await planningService.setActivePlan({ planId: plan.id });
+            if (!setActiveResult) {
+                console.warn(`Warning: Failed to set plan ${plan.id} as active for persona ${context.activePersona?.id}`);
+            }
+            // Format response using service method
+            const planStructureJson = await planningService.formatPlanStructure(plan);
+            const planStructure = JSON.parse(planStructureJson);
+            const response = [
+                `✅ Created plan: "${plan.title}"`,
+                `Plan ID: ${plan.id}`,
+                `Persona: ${context.activePersona?.id || 'unknown'}`,
+                '',
+                `Extracted ${plan.phases.length} phases:`,
+                ...plan.phases.map((phase, i) => `${i + 1}. ${phase.title}`),
+                '',
+                '## Plan Structure (for AI reference)',
+                '```json',
+                JSON.stringify(planStructure, null, 2),
+                '```',
+                '',
+                '## How to Update This Plan',
+                'When calling plan update, reference the structure above to:',
+                '1. Complete todos by exact content match: `completeTodo: "exact todo text"`',
+                '2. Update phase status: `updatePhase: { phaseNumber: 1, status: "completed" }`',
+                '3. Add new todos: `updatePhase: { phaseNumber: 1, addTodo: "new task" }`',
+                '',
+                'Example update calls:',
+                '',
+                '**Single operations (backward compatible):**',
+                '```json',
+                JSON.stringify({
+                    operation: 'update',
+                    updates: {
+                        updatePhase: {
+                            phaseNumber: 1,
+                            status: 'in_progress',
+                            completeTodo: 'First todo content from structure above',
+                        },
+                    },
+                }, null, 2),
+                '```',
+                '',
+                '**Bulk operations (NEW):**',
+                '```json',
+                JSON.stringify({
+                    operation: 'update',
+                    updates: {
+                        updatePhase: {
+                            phaseNumber: 1,
+                            status: 'completed',
+                            completeTodos: ['First todo content', 'Second todo content', 'Third todo content'],
+                        },
+                    },
+                }, null, 2),
+                '```',
+                '',
+                '**Multiple phase updates:**',
+                '```json',
+                JSON.stringify({
+                    operation: 'update',
+                    updates: {
+                        updatePhases: [
+                            {
+                                phaseNumber: 1,
+                                status: 'completed',
+                                completeTodos: ['Todo 1', 'Todo 2'],
+                            },
+                            {
+                                phaseNumber: 2,
+                                status: 'in_progress',
+                                addTodos: ['New task 1', 'New task 2'],
+                            },
+                        ],
+                    },
+                }, null, 2),
+                '```',
+                '',
+                'Use "plan operation=status" to see the current status.',
+            ].join('\n');
+            return createSuccessResult(response);
+        }
+        catch (error) {
+            return createErrorResult(`Failed to create plan: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    static async handleUpdate(args, context) {
+        try {
+            // Get the plan to update
+            let plan;
+            // Create service with RequestContext
+            const planningService = new PlanningService(context);
+            if (args.planId) {
+                if (!context.activePersona) {
+                    return createErrorResult('Active persona is required');
+                }
+                plan = await planningService.loadPlan({ planId: args.planId });
+                if (!plan) {
+                    return createErrorResult(`Plan not found: ${args.planId}`);
+                }
+            }
+            else {
+                if (!context.activePersona) {
+                    return createErrorResult('Active persona is required');
+                }
+                plan = await planningService.getActivePlan();
+                if (!plan) {
+                    return createErrorResult('No active plan found. Specify a planId or accept a new plan.');
+                }
+            }
+            // Apply updates using service
+            const updatedPlan = await planningService.updatePlan({
+                planId: plan.id,
+                updates: args.updates || {},
+            });
+            // Generate status report using service
+            const statusReport = await planningService.generateStatusReport(updatedPlan);
+            const response = [
+                `✅ Updated plan: "${updatedPlan.title}"`,
+                '',
+                'Plan updated successfully.',
+                '',
+                statusReport,
+            ].join('\n');
+            return createSuccessResult(response);
+        }
+        catch (error) {
+            return createErrorResult(`Failed to update plan: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    static async handleStatus(args, context) {
+        try {
+            if (!context.activePersona) {
+                return createErrorResult('No active persona found. Please select a persona first.');
+            }
+            // For non-verbose, use the summary method for better performance
+            if (!args.verbose) {
+                // Create service with RequestContext
+                const planningService = new PlanningService(context);
+                const planSummary = await planningService.getActivePlanSummary();
+                if (!planSummary) {
+                    return createErrorResult(`No active plan found for persona "${context.activePersona.id}". Use "plan operation=list" to see all plans.`);
+                }
+                // Generate status report using a temporary plan object from summary
+                const tempPlan = {
+                    ...planSummary,
+                    overview: '',
+                    phases: [],
+                    metadata: {
+                        totalPhases: planSummary.currentState.overallProgress.totalPhases,
+                        completedPhases: planSummary.currentState.overallProgress.completedPhases,
+                        totalTodos: planSummary.currentState.overallProgress.totalTodos,
+                        completedTodos: planSummary.currentState.overallProgress.completedTodos,
+                        lastChanges: [],
+                        contributors: [],
+                        tags: [],
+                    },
+                    created: '',
+                };
+                const statusReport = await planningService.generateStatusReport(tempPlan);
+                return createSuccessResult(statusReport);
+            }
+            else {
+                // For verbose, load the full plan
+                // Create service with RequestContext
+                const planningService = new PlanningService(context);
+                const plan = await planningService.getActivePlan();
+                if (!plan) {
+                    return createErrorResult(`No active plan found for persona "${context.activePersona.id}". Use "plan operation=list" to see all plans.`);
+                }
+                const formattedPlan = await planningService.formatPlan(plan, true);
+                return createSuccessResult(formattedPlan);
+            }
+        }
+        catch (error) {
+            return createErrorResult(`Failed to get plan status: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    static async handleReport(args, context) {
+        try {
+            if (!context.activePersona) {
+                return createErrorResult('No active persona found. Please select a persona first.');
+            }
+            // Create service with RequestContext
+            const planningService = new PlanningService(context);
+            const plan = await planningService.getActivePlan();
+            if (!plan) {
+                return createErrorResult('No active plan found.');
+            }
+            const report = await planningService.formatPlan(plan, true);
+            if (args.saveToFile) {
+                // Save report to storage
+                const filename = `plan-report-${plan.id}-${new Date().toISOString().split('T')[0]}.md`;
+                const path = `reports/${filename}`;
+                await context.storage?.storeUserData(path, report, context.userId);
+                const response = [`Report saved to: ${path}`, '', report].join('\n');
+                return createSuccessResult(response);
+            }
+            const response = report;
+            return createSuccessResult(response);
+        }
+        catch (error) {
+            return createErrorResult(`Failed to generate report: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    static async handleList(args, context) {
+        try {
+            if (!context.activePersona) {
+                return createErrorResult('No active persona found. Please select a persona first.');
+            }
+            const status = args.listStatus || 'active';
+            // Create service with RequestContext
+            const planningService = new PlanningService(context);
+            // Map 'completed' to 'all' since we need to load all plans to filter by status
+            const serviceStatus = status === 'completed' ? 'all' : status;
+            const allPlans = await planningService.listPlans({
+                type: serviceStatus === 'all' ? undefined : serviceStatus
+            });
+            // Filter by actual plan status if we're looking for completed plans
+            const plans = status === 'completed'
+                ? allPlans.filter(plan => plan.status === 'complete')
+                : allPlans;
+            if (plans.length === 0) {
+                return createSuccessResult(`No ${status} plans found for persona "${context.activePersona.id}".`);
+            }
+            // Get the active plan to mark it
+            const activePlan = await planningService.getActivePlan();
+            const activePlanId = activePlan?.id;
+            // Format the plan list with active plan indicator
+            const lines = [`📋 Plans for persona "${context.activePersona?.id || 'unknown'}":`];
+            lines.push('');
+            if (plans.length === 0) {
+                lines.push('No plans found. Create one with: plan operation="accept"');
+            }
+            else {
+                lines.push('Available plans:');
+                lines.push('');
+                for (const plan of plans) {
+                    const isActive = plan.id === activePlanId;
+                    const statusEmoji = plan.type === 'active' ? '🟢' : plan.status === 'complete' ? '✅' : '📦';
+                    const activeMarker = isActive ? ' ⭐ [ACTIVE]' : '';
+                    lines.push(`${statusEmoji} **${plan.title}** (${plan.id})${activeMarker}`);
+                    lines.push(`   Progress: ${plan.currentState.overallProgress.percentComplete}% - ${plan.currentState.overallProgress.completedPhases}/${plan.phases.length} phases, ${plan.currentState.overallProgress.completedTodos}/${plan.currentState.overallProgress.totalTodos} tasks`);
+                    lines.push(`   Last updated: ${new Date(plan.lastUpdated).toLocaleDateString()}`);
+                    lines.push('');
+                }
+            }
+            return createSuccessResult(lines.join('\n'));
+        }
+        catch (error) {
+            return createErrorResult(`Failed to list plans: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    static async handleArchive(args, context) {
+        try {
+            if (!context.activePersona) {
+                return createErrorResult('No active persona found. Please select a persona first.');
+            }
+            // planId is required for archive operation
+            if (!args.planId) {
+                return createErrorResult('Plan ID is required for archive operation. Use "plan operation=list" to see available plans.');
+            }
+            // Create service with RequestContext
+            const planningService = new PlanningService(context);
+            // Load the specific plan to archive  
+            const plan = await planningService.loadPlan({ planId: args.planId });
+            if (!plan) {
+                return createErrorResult(`Plan not found: ${args.planId}. Use "plan operation=list" to see available plans.`);
+            }
+            // Archive the plan with explicit args
+            const archived = await planningService.archivePlan({
+                planId: plan.id,
+                reason: args.reason
+            });
+            if (!archived) {
+                return createErrorResult('Failed to archive plan.');
+            }
+            return createSuccessResult(`✅ Archived plan: "${plan.title}"\nReason: ${args.reason || 'Completed'}`);
+        }
+        catch (error) {
+            return createErrorResult(`Failed to archive plan: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    static async handleSwitch(args, context) {
+        try {
+            if (!context.activePersona) {
+                return createErrorResult('No active persona found. Please select a persona first.');
+            }
+            if (!args.planId) {
+                return createErrorResult('Plan ID is required for switch operation.');
+            }
+            // Create service with RequestContext
+            const planningService = new PlanningService(context);
+            // Use the new switchToPlan method which handles both active and archived plans
+            // It will automatically unarchive if needed
+            const switchedPlan = await planningService.switchToPlan(args.planId);
+            // Generate a success message with plan summary
+            const state = switchedPlan.currentState;
+            const response = [
+                `✅ Switched active plan to: "${switchedPlan.title}"`,
+                `Plan ID: ${switchedPlan.id}`,
+                `Status: ${switchedPlan.status}`,
+                `Progress: ${state.overallProgress.percentComplete}% (${state.overallProgress.completedPhases}/${state.overallProgress.totalPhases} phases, ${state.overallProgress.completedTodos}/${state.overallProgress.totalTodos} tasks)`,
+                '',
+                'Use "plan operation=status" to see the current status.',
+            ].join('\n');
+            return createSuccessResult(response);
+        }
+        catch (error) {
+            return createErrorResult(`Failed to switch plan: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    static async handleWatch(args, context) {
+        try {
+            // Check if we have an existing watcher
+            if (watcherInstance) {
+                const isRunning = watcherInstance.isRunning();
+                if (isRunning) {
+                    // Stop the old watcher before creating a new one
+                    await watcherInstance.stop();
+                }
+            }
+            // Always create a new instance with the current context
+            // This ensures we get the latest activePersona from the MCP server
+            watcherInstance = new PlanWatcherService(context);
+            // Start the watcher with provided options
+            const options = {
+                port: args.port,
+                autoOpen: args.autoOpen,
+                showAll: args.showAll,
+            };
+            const result = await watcherInstance.start(options);
+            if (!result.success) {
+                return createErrorResult(result.error.message);
+            }
+            const { url, port, autoOpen, plansLoaded } = result.data;
+            const response = [
+                '🔍 Plan watcher started successfully!',
+                '',
+                `📊 Dashboard URL: ${url}`,
+                `🔌 Port: ${port}`,
+                `📂 Plans loaded: ${plansLoaded}`,
+                autoOpen ? '🌐 Browser will open automatically' : '🔗 Open the URL in your browser',
+                '',
+                'The dashboard will auto-refresh when plans change.',
+                'Use "plan operation=stop-watch" to stop the dashboard.',
+            ].join('\n');
+            return createSuccessResult(response);
+        }
+        catch (error) {
+            return createErrorResult(`Failed to start plan watcher: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    static async handleStopWatch(_args, _context) {
+        try {
+            if (!watcherInstance) {
+                return createErrorResult('Plan watcher is not running');
+            }
+            const result = await watcherInstance.stop();
+            if (!result.success) {
+                return createErrorResult(result.error.message);
+            }
+            // Clear the singleton instance
+            watcherInstance = null;
+            return createSuccessResult('✅ Plan watcher stopped successfully');
+        }
+        catch (error) {
+            return createErrorResult(`Failed to stop plan watcher: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+}
+//# sourceMappingURL=plan.tool.js.map