orquesta-cli 0.1.12

package/src/agents/planner/index.ts

@@ -0,0 +1,544 @@
+/**
+ * Planning Agent
+ *
+ * System Planning Agent with full shell access.
+ * - Clarify requirements with ask_to_user
+ * - Create comprehensive TODO lists for Execution LLM
+ * - Supports parallel docs search decision
+ */
+
+// DISABLED: docs-search feature temporarily disabled (used by getDocsFolderStructure)
+// import * as fs from 'fs/promises';
+// import * as path from 'path';
+// import * as os from 'os';
+import { LLMClient } from '../../core/llm/llm-client.js';
+import { Message, TodoItem, PlanningResult, TodoStatus } from '../../types/index.js';
+import { logger } from '../../utils/logger.js';
+import { buildPlanningSystemPrompt } from '../../prompts/agents/planning.js';
+import { toolRegistry } from '../../tools/registry.js';
+// DISABLED: docs-search feature temporarily disabled
+// import {
+//   buildDocsSearchDecisionPrompt,
+//   parseDocsSearchDecision,
+//   DOCS_SEARCH_DECISION_RETRY_PROMPT,
+// } from '../../prompts/agents/docs-search-decision.js';
+import {
+  AskUserResponse,
+  AskUserCallback,
+} from '../../tools/llm/simple/user-interaction-tools.js';
+
+/**
+ * Result of parallel planning with docs decision
+ */
+export interface PlanningWithDocsResult extends PlanningResult {
+  docsSearchNeeded: boolean;
+}
+
+/**
+ * Planning LLM
+ * System Planning Agent that converts user requests into executable TODO lists
+ * Supports ask_to_user for requirement clarification
+ */
+export class PlanningLLM {
+  private llmClient: LLMClient;
+  private askUserCallback: AskUserCallback | null = null;
+
+  constructor(llmClient: LLMClient) {
+    this.llmClient = llmClient;
+  }
+
+  /**
+   * Set the ask-user callback for Planning LLM
+   * This enables the ask_to_user tool during planning
+   */
+  setAskUserCallback(callback: AskUserCallback): void {
+    logger.flow('Setting ask-user callback for Planning LLM');
+    this.askUserCallback = callback;
+  }
+
+  /**
+   * Clear ask-user callback
+   */
+  clearAskUserCallback(): void {
+    logger.flow('Clearing ask-user callback for Planning LLM');
+    this.askUserCallback = null;
+  }
+
+  /**
+   * Convert user request to TODO list
+   * Uses actual tool definitions for Planning LLM
+   * Supports ask_to_user for requirement clarification (loops until final decision)
+   * Returns clarificationMessages for caller to inject into conversation history
+   * @param userRequest The user's request
+   * @param contextMessages Optional context messages (e.g., docs search results)
+   */
+  async generateTODOList(
+    userRequest: string,
+    contextMessages?: Message[],
+  ): Promise<PlanningResult> {
+    // Build dynamic system prompt with available tools
+    const toolSummary = toolRegistry.getToolSummaryForPlanning();
+    const optionalToolsInfo = toolRegistry.getEnabledOptionalToolsInfo();
+    const systemPrompt = buildPlanningSystemPrompt(toolSummary, optionalToolsInfo);
+
+    // Track clarification messages (ask_to_user Q&A) to return to caller
+    const clarificationMessages: Message[] = [];
+
+    const messages: Message[] = [
+      {
+        role: 'system',
+        content: systemPrompt,
+      },
+    ];
+
+    // Include conversation history (excluding system messages)
+    // System prompts are injected per-LLM call, not stored in history
+    if (contextMessages && contextMessages.length > 0) {
+      const conversationMsgs = contextMessages.filter(m => m.role !== 'system');
+      messages.push(...conversationMsgs);
+    }
+
+    // Check if last message is already the same user request (avoid duplicate)
+    const lastMsg = messages[messages.length - 1];
+    if (!(lastMsg?.role === 'user' && lastMsg?.content === userRequest)) {
+      // Add [NEW REQUEST] marker to distinguish from previous conversation
+      // This helps LLM understand this is a fresh request, not continuation of completed tasks
+      messages.push({
+        role: 'user',
+        content: `[NEW REQUEST]\n${userRequest}`,
+      });
+    }
+
+    // Get Planning tool definitions (ask_to_user, create_todos, respond_to_user)
+    const planningTools = toolRegistry.getLLMPlanningToolDefinitions();
+
+    const MAX_RETRIES = 3;
+    const MAX_ASK_ITERATIONS = 5;
+    let askIterations = 0;
+    let lastError: Error | null = null;
+
+    // Main planning loop - continues until create_todos or respond_to_user is called
+    while (askIterations < MAX_ASK_ITERATIONS) {
+      let shouldContinueMainLoop = false; // Track if we should continue after ask_to_user
+
+      for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+        try {
+          // Add retry prompt if this is a retry attempt
+          if (attempt > 1) {
+            messages.push({
+              role: 'user',
+              content: `[RETRY ${attempt}/${MAX_RETRIES}] ⚠️ CRITICAL: You are the PLANNING LLM, not the Execution LLM.
+
+You have ONLY 3 tools available:
+1. 'ask_to_user' - To clarify ambiguous requirements (use FIRST if unclear)
+2. 'create_todos' - For ANY action/implementation request
+3. 'respond_to_user' - For pure knowledge questions/greetings only
+
+❌ DO NOT use tools like 'write_todos', 'read_file', 'bash', etc. Those are for Execution LLM, NOT you.
+❌ You saw those tools in conversation history, but they are NOT available to you.
+
+Previous error: ${lastError?.message || 'Invalid response'}
+
+Choose one of your 3 tools now.`,
+            });
+            logger.warn(`Planning LLM retry attempt ${attempt}/${MAX_RETRIES}`, { lastError: lastError?.message });
+          }
+
+          const response = await this.llmClient.chatCompletion({
+            messages,
+            tools: planningTools,
+            tool_choice: 'required',
+            temperature: 0.7,
+            max_tokens: 2000,
+          });
+
+          // Debug: Log raw response structure
+          const choicesCount = response.choices?.length ?? 0;
+          const message = response.choices?.[0]?.message;
+          const toolCalls = message?.tool_calls;
+          const finishReason = response.choices?.[0]?.finish_reason;
+
+          logger.debug('Planning LLM response', {
+            choicesCount,
+            hasMessage: !!message,
+            hasToolCalls: !!(toolCalls && toolCalls.length > 0),
+            hasContent: !!message?.content,
+            contentLength: message?.content?.length ?? 0,
+            finishReason,
+            toolCallsCount: toolCalls?.length ?? 0,
+          });
+
+          // Handle tool call
+          if (toolCalls && toolCalls.length > 0) {
+            const toolCall = toolCalls[0]!;
+            const toolName = toolCall.function?.name;
+
+            let toolArgs;
+            try {
+              toolArgs = JSON.parse(toolCall.function?.arguments || '{}');
+            } catch (error) {
+              logger.warn('Failed to parse tool arguments', { args: toolCall.function?.arguments, error });
+              lastError = error as Error;
+              continue; // Retry
+            }
+
+            // Handle ask_to_user - clarify requirements before planning
+            if (toolName === 'ask_to_user') {
+              logger.flow('Planning LLM asking user for clarification');
+
+              const question = toolArgs.question as string;
+              const options = toolArgs.options as string[];
+
+              if (!question || !Array.isArray(options) || options.length < 2) {
+                logger.warn('ask_to_user called with invalid parameters', { toolArgs });
+                lastError = new Error('ask_to_user requires a question and 2-4 options');
+                continue; // Retry
+              }
+
+              askIterations++;
+
+              // Check if callback is available
+              if (!this.askUserCallback) {
+                logger.warn('ask_to_user called but no callback is set, forcing create_todos');
+                messages.push({
+                  role: 'assistant',
+                  content: `[ask_to_user was called but user interaction is not available.]`,
+                });
+                messages.push({
+                  role: 'user',
+                  content: `User interaction is unavailable. You MUST call 'create_todos' now with your best judgment. Do NOT call ask_to_user again.`,
+                });
+                shouldContinueMainLoop = true;
+                break; // Exit retry loop, continue main loop
+              }
+
+              try {
+                // Record the assistant's question in history
+                const assistantMsg: Message = {
+                  role: 'assistant',
+                  content: `[Clarification needed] ${question}\nOptions: ${options.join(', ')}`,
+                };
+                messages.push(assistantMsg);
+                clarificationMessages.push(assistantMsg);
+
+                // Call the UI callback to ask user
+                const userResponse: AskUserResponse = await this.askUserCallback({ question, options });
+
+                // Build user response text
+                const userAnswerText = userResponse.isOther && userResponse.customText
+                  ? userResponse.customText
+                  : userResponse.selectedOption;
+
+                // Record user's response in history
+                const userMsg: Message = {
+                  role: 'user',
+                  content: `[User's answer] ${userAnswerText}`,
+                };
+                messages.push(userMsg);
+                clarificationMessages.push(userMsg);
+
+                logger.flow('User responded to clarification question', {
+                  question,
+                  answer: userAnswerText,
+                  isCustom: userResponse.isOther,
+                });
+
+                // Continue main loop - LLM will process the answer and decide next step
+                shouldContinueMainLoop = true;
+                break; // Exit retry loop, continue main loop
+
+              } catch (error) {
+                logger.error('Error during ask_to_user', error as Error);
+                lastError = error as Error;
+                // Continue retry loop
+                continue;
+              }
+            }
+
+            // Handle create_todos - final planning decision
+            if (toolName === 'create_todos') {
+              logger.flow('TODO list created via create_todos tool');
+
+              // Validate todos is an array (handle string-wrapped JSON from LLM)
+              let rawTodos = toolArgs.todos;
+
+              // If todos is a string, try to parse it as JSON
+              if (typeof rawTodos === 'string') {
+                try {
+                  rawTodos = JSON.parse(rawTodos);
+                  logger.debug('Parsed string-wrapped todos array');
+                } catch {
+                  logger.warn('Failed to parse string todos as JSON', { todos: rawTodos });
+                }
+              }
+
+              if (!Array.isArray(rawTodos)) {
+                logger.warn('create_todos called with non-array todos', { toolArgs });
+                lastError = new Error('Planning LLM returned invalid todos format (expected array).');
+                continue; // Retry
+              }
+
+              const todos: TodoItem[] = rawTodos.map((todo: any, index: number) => ({
+                id: todo.id || `todo-${Date.now()}-${index}`,
+                title: todo.title || 'Untitled task',
+                // First TODO starts as in_progress, rest are pending
+                status: (index === 0 ? 'in_progress' : 'pending') as TodoStatus,
+              }));
+
+              return {
+                todos,
+                complexity: toolArgs.complexity || 'moderate',
+                clarificationMessages: clarificationMessages.length > 0 ? clarificationMessages : undefined,
+              };
+            }
+
+            // Handle respond_to_user - direct response without TODOs
+            if (toolName === 'respond_to_user') {
+              logger.flow('Direct response via respond_to_user tool');
+              const responseText = toolArgs.response || '';
+
+              if (!responseText) {
+                logger.warn('respond_to_user called with empty response');
+                lastError = new Error('Planning LLM returned empty response.');
+                continue; // Retry
+              }
+
+              return {
+                todos: [],
+                complexity: 'simple',
+                directResponse: responseText,
+                clarificationMessages: clarificationMessages.length > 0 ? clarificationMessages : undefined,
+              };
+            }
+
+            // Unknown tool - retry
+            logger.warn(`Unknown tool called: ${toolName}`);
+            lastError = new Error(`Invalid tool "${toolName}". You only have 3 tools: ask_to_user, create_todos, or respond_to_user. Tools like write_todos are for Execution LLM, not Planning LLM.`);
+            continue; // Retry
+          }
+
+          // No tool call - this should not happen with tool_choice: "required"
+          const contentOnly = message?.content;
+          if (contentOnly) {
+            logger.warn(`Planning LLM returned content without tool call (attempt ${attempt}/${MAX_RETRIES})`, {
+              contentPreview: contentOnly.substring(0, 100),
+            });
+            lastError = new Error(
+              'You MUST call one of your tools: ask_to_user, create_todos, or respond_to_user. Do NOT respond with plain text.'
+            );
+          } else {
+            logger.warn(`Planning LLM returned no tool call and no content (attempt ${attempt}/${MAX_RETRIES})`);
+            lastError = new Error('Planning LLM must use one of: ask_to_user, create_todos, or respond_to_user');
+          }
+          // Continue to next retry
+        } catch (error) {
+          // Network or API error - will retry
+          logger.warn(`Planning LLM error (attempt ${attempt}/${MAX_RETRIES}):`, error as Error);
+          lastError = error as Error;
+          // Continue to next retry
+        }
+      }
+
+      // If ask_to_user was successful, continue main loop for next LLM call
+      if (shouldContinueMainLoop) {
+        continue;
+      }
+
+      // All retries exhausted without successful ask_to_user - break to fallback
+      break;
+    }
+
+    // All retries exhausted - use fallback
+    logger.warn('All planning retries exhausted, using fallback TODO', { lastError: lastError?.message });
+    return {
+      todos: [
+        {
+          id: `todo-${Date.now()}`,
+          title: userRequest.length > 100 ? userRequest.substring(0, 100) + '...' : userRequest,
+          status: 'in_progress',
+        },
+      ],
+      complexity: 'simple',
+      clarificationMessages: clarificationMessages.length > 0 ? clarificationMessages : undefined,
+    };
+  }
+
+  /**
+   * Generate TODO list with parallel docs search decision
+   * Runs planning and docs decision in parallel, then injects docs search TODO if needed
+   *
+   * NOTE: docs-search feature is currently DISABLED. Always returns docsSearchNeeded: false
+   */
+  async generateTODOListWithDocsDecision(
+    userRequest: string,
+    contextMessages?: Message[]
+  ): Promise<PlanningWithDocsResult> {
+    logger.enter('PlanningLLM.generateTODOListWithDocsDecision', { requestLength: userRequest.length });
+    logger.startTimer('parallel-planning');
+
+    // DISABLED: docs-search feature temporarily disabled
+    // Only run planning, skip docs search decision
+    const planningResult = await this.generateTODOList(userRequest, contextMessages);
+
+    logger.vars(
+      { name: 'todoCount', value: planningResult.todos.length },
+      { name: 'docsSearchNeeded', value: false }
+    );
+
+    logger.endTimer('parallel-planning');
+    logger.exit('PlanningLLM.generateTODOListWithDocsDecision', { docsSearchNeeded: false });
+
+    return {
+      ...planningResult,
+      docsSearchNeeded: false,
+    };
+
+    /* DISABLED: Original docs-search logic preserved for future use
+    // Run planning and docs decision in parallel
+    const [planningResult, docsSearchNeeded] = await Promise.all([
+      this.generateTODOList(userRequest, contextMessages),
+      this.shouldSearchDocs(userRequest),
+    ]);
+
+    logger.vars(
+      { name: 'todoCount', value: planningResult.todos.length },
+      { name: 'docsSearchNeeded', value: docsSearchNeeded }
+    );
+
+    // If docs search is needed, prepend a docs search TODO
+    if (docsSearchNeeded) {
+      const docsSearchTodo: TodoItem = {
+        id: `todo-docs-${Date.now()}`,
+        title: 'Search local documentation (use call_docs_search_agent)',
+        status: 'pending' as TodoStatus,
+      };
+
+      logger.flow('Prepended docs search TODO');
+      logger.endTimer('parallel-planning');
+      logger.exit('PlanningLLM.generateTODOListWithDocsDecision', { docsSearchNeeded: true });
+
+      return {
+        ...planningResult,
+        todos: [docsSearchTodo, ...planningResult.todos],
+        docsSearchNeeded: true,
+      };
+    }
+
+    logger.endTimer('parallel-planning');
+    logger.exit('PlanningLLM.generateTODOListWithDocsDecision', { docsSearchNeeded: false });
+
+    return {
+      ...planningResult,
+      docsSearchNeeded: false,
+    };
+    */
+  }
+
+  /* DISABLED: docs-search feature temporarily disabled
+  private async shouldSearchDocs(userMessage: string): Promise<boolean> {
+    logger.enter('PlanningLLM.shouldSearchDocs', { messageLength: userMessage.length });
+
+    // Get folder structure
+    const folderStructure = await this.getDocsFolderStructure();
+
+    // If no docs available, skip search
+    if (
+      folderStructure.includes('empty') ||
+      folderStructure.includes('does not exist')
+    ) {
+      logger.flow('No docs available, skipping search decision');
+      logger.exit('PlanningLLM.shouldSearchDocs', { decision: false, reason: 'no-docs' });
+      return false;
+    }
+
+    // Build prompt
+    const prompt = buildDocsSearchDecisionPrompt(folderStructure, userMessage);
+
+    const messages: Message[] = [
+      { role: 'user', content: prompt },
+    ];
+
+    let retries = 0;
+    const MAX_RETRIES = 2;
+
+    while (retries <= MAX_RETRIES) {
+      logger.flow(`Asking LLM for docs search decision (attempt ${retries + 1})`);
+
+      const response = await this.llmClient.chatCompletion({
+        messages,
+        temperature: 0.1,
+        max_tokens: 10,
+      });
+
+      const content = response.choices[0]?.message?.content || '';
+      logger.debug('LLM decision response', { content });
+
+      const decision = parseDocsSearchDecision(content);
+
+      if (decision !== null) {
+        logger.exit('PlanningLLM.shouldSearchDocs', { decision, attempts: retries + 1 });
+        return decision;
+      }
+
+      // Invalid response, retry
+      retries++;
+      if (retries <= MAX_RETRIES) {
+        messages.push({ role: 'assistant', content });
+        messages.push({ role: 'user', content: DOCS_SEARCH_DECISION_RETRY_PROMPT });
+        logger.warn('Invalid decision response, retrying', { response: content });
+      }
+    }
+
+    // Default to false if all retries failed
+    logger.warn('All decision retries failed, defaulting to no search');
+    logger.exit('PlanningLLM.shouldSearchDocs', { decision: false, reason: 'retries-exhausted' });
+    return false;
+  }
+
+  private async getDocsFolderStructure(): Promise<string> {
+    const docsBasePath = path.join(os.homedir(), '.hanseol', 'docs');
+
+    try {
+      const entries = await fs.readdir(docsBasePath, { withFileTypes: true });
+
+      const lines: string[] = [];
+
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          // Depth 0: Show top-level directory
+          lines.push(`📁 ${entry.name}/`);
+
+          // Depth 1: Show only immediate subdirectory names
+          try {
+            const subPath = path.join(docsBasePath, entry.name);
+            const subEntries = await fs.readdir(subPath, { withFileTypes: true });
+            const subDirs = subEntries.filter(e => e.isDirectory());
+
+            if (subDirs.length > 0) {
+              const subDirNames = subDirs.map(d => d.name).join(', ');
+              lines.push(`   └── [${subDirNames}]`);
+            }
+          } catch {
+            // Ignore errors reading subdirectories
+          }
+        }
+        // Skip files at root level - only show directories
+      }
+
+      if (lines.length === 0) {
+        return '(empty - no documentation available)';
+      }
+
+      return lines.join('\n');
+    } catch (error) {
+      const err = error as NodeJS.ErrnoException;
+      if (err.code === 'ENOENT') {
+        return '(docs directory does not exist)';
+      }
+      return '(error reading docs directory)';
+    }
+  }
+  */
+}
+
+export default PlanningLLM;