orquesta-cli 0.1.12

package/src/tools/llm/simple/final-response-tool.ts

@@ -0,0 +1,180 @@
+/**
+ * Final Response Tool
+ *
+ * Tool used by LLM to deliver final response
+ * - Only succeeds if all TODOs are completed
+ * - Returns error if incomplete TODOs exist (doesn't exit, LLM retries)
+ * - Shows as assistant message on success
+ */
+
+import { LLMSimpleTool, ToolResult, ToolCategory } from '../../types.js';
+import { ToolDefinition } from '../../../types/index.js';
+import { logger } from '../../../utils/logger.js';
+import { TodoItem } from '../../../types/index.js';
+
+/**
+ * TODO status query callback type
+ */
+export type GetTodosCallback = () => TodoItem[];
+
+/**
+ * Final response completion callback type
+ * Returns true to exit execution
+ */
+export type FinalResponseCallback = (message: string) => void;
+
+// Global callbacks - set by orchestrator
+let getTodosCallback: GetTodosCallback | null = null;
+let finalResponseCallback: FinalResponseCallback | null = null;
+
+/**
+ * Set the TODO getter callback
+ */
+export function setGetTodosCallback(callback: GetTodosCallback): void {
+  logger.flow('Setting getTodos callback for final_response');
+  getTodosCallback = callback;
+}
+
+/**
+ * Set the final response callback
+ */
+export function setFinalResponseCallback(callback: FinalResponseCallback): void {
+  logger.flow('Setting finalResponse callback');
+  finalResponseCallback = callback;
+}
+
+/**
+ * Clear callbacks
+ */
+export function clearFinalResponseCallbacks(): void {
+  logger.flow('Clearing final response callbacks');
+  getTodosCallback = null;
+  finalResponseCallback = null;
+}
+
+/**
+ * Check if all todos are completed
+ */
+function areAllTodosCompleted(todos: TodoItem[]): boolean {
+  if (todos.length === 0) return true;
+  return todos.every(t => t.status === 'completed' || t.status === 'failed');
+}
+
+/**
+ * Get incomplete todos summary
+ */
+function getIncompleteTodosSummary(todos: TodoItem[]): string {
+  const incomplete = todos.filter(t => t.status !== 'completed' && t.status !== 'failed');
+  if (incomplete.length === 0) return '';
+
+  const list = incomplete.map(t => `- [${t.status}] ${t.title}`).join('\n');
+  return `Incomplete TODOs:\n${list}`;
+}
+
+/**
+ * final_response Tool Definition
+ */
+const FINAL_RESPONSE_DEFINITION: ToolDefinition = {
+  type: 'function',
+  function: {
+    name: 'final_response',
+    description: `Use this tool to deliver your final response to the user after completing all tasks.
+
+IMPORTANT:
+- You MUST complete all TODOs before calling this tool
+- If any TODO is not completed, this tool will return an error
+- After all tasks are done, use this tool to summarize what was accomplished
+
+Example:
+{
+  "message": "I've completed all the requested tasks:\\n\\n1. Fixed the bug in the login form\\n2. Added input validation\\n3. Updated the tests\\n\\nAll changes have been committed."
+}`,
+    parameters: {
+      type: 'object',
+      properties: {
+        message: {
+          type: 'string',
+          description: 'Your final response message to the user. Summarize what was accomplished.',
+        },
+      },
+      required: ['message'],
+    },
+  },
+};
+
+/**
+ * final_response Tool Implementation
+ */
+async function executeFinalResponse(args: Record<string, unknown>): Promise<ToolResult> {
+  logger.enter('executeFinalResponse', args);
+
+  const message = args['message'] as string;
+
+  if (!message || typeof message !== 'string') {
+    logger.warn('Missing or invalid message');
+    return {
+      success: false,
+      error: 'Missing required parameter: message is required',
+    };
+  }
+
+  // Get current todos
+  if (!getTodosCallback) {
+    logger.warn('getTodos callback not set');
+    // If no callback, allow final response (might be in a context without todos)
+    if (finalResponseCallback) {
+      finalResponseCallback(message);
+    }
+    return {
+      success: true,
+      result: message,
+      metadata: { isFinalResponse: true },
+    };
+  }
+
+  const todos = getTodosCallback();
+
+  // Check if all todos are completed
+  if (!areAllTodosCompleted(todos)) {
+    const incompleteSummary = getIncompleteTodosSummary(todos);
+    logger.flow('Final response rejected - incomplete TODOs');
+    logger.debug('Incomplete TODOs', { count: todos.filter(t => t.status !== 'completed' && t.status !== 'failed').length });
+
+    return {
+      success: false,
+      error: `Cannot deliver final response: Please complete all TODOs first.\n\n${incompleteSummary}\n\nMark each TODO as "completed" or "failed" using write_todos before calling final_response.`,
+    };
+  }
+
+  // All todos completed - deliver final response
+  logger.flow('All TODOs completed - delivering final response');
+
+  if (finalResponseCallback) {
+    finalResponseCallback(message);
+  }
+
+  return {
+    success: true,
+    result: message,
+    metadata: { isFinalResponse: true },
+  };
+}
+
+/**
+ * LLM Simple Tool: final_response
+ */
+export const FinalResponseTool: LLMSimpleTool = {
+  definition: FINAL_RESPONSE_DEFINITION,
+  execute: executeFinalResponse,
+  categories: ['llm-simple'] as ToolCategory[],
+  description: 'Deliver final response to user (requires all TODOs completed)',
+};
+
+/**
+ * Get final_response tool definition for LLM
+ */
+export function getFinalResponseToolDefinition(): ToolDefinition {
+  return FINAL_RESPONSE_DEFINITION;
+}
+
+export default FinalResponseTool;

package/src/tools/llm/simple/index.ts

@@ -0,0 +1,42 @@
+/**
+ * LLM Simple Tools Index
+ *
+ * Tools called by LLM via tool_call (no Sub-LLM)
+ * Exports appropriate shell tools based on platform
+ */
+
+import { isNativeWindows } from '../../../utils/platform-utils.js';
+import { LLMSimpleTool } from '../../types.js';
+
+// Common tools (all platforms)
+export * from './file-tools.js';
+export * from './todo-tools.js';
+export * from './ask-user-tool.js';
+export * from './final-response-tool.js';
+
+// Bash tools (WSL/Linux)
+export * from './bash-tool.js';
+import { bashTool } from './bash-tool.js';
+import { BACKGROUND_BASH_TOOLS } from './background-bash-tool.js';
+export { BACKGROUND_BASH_TOOLS } from './background-bash-tool.js';
+
+// PowerShell tools (Native Windows)
+export * from './powershell-tool.js';
+import { powershellTool } from './powershell-tool.js';
+import { BACKGROUND_POWERSHELL_TOOLS } from './background-powershell-tool.js';
+export { BACKGROUND_POWERSHELL_TOOLS } from './background-powershell-tool.js';
+
+/**
+ * Get shell tools based on current platform
+ *
+ * - Native Windows: powershell + powershell_background_*
+ * - WSL/Linux: bash + bash_background_*
+ */
+export function getShellTools(): LLMSimpleTool[] {
+  if (isNativeWindows()) {
+    return [powershellTool, ...BACKGROUND_POWERSHELL_TOOLS];
+  }
+
+  // WSL/Linux
+  return [bashTool, ...BACKGROUND_BASH_TOOLS];
+}

package/src/tools/llm/simple/planning-tools.ts

@@ -0,0 +1,143 @@
+/**
+ * Planning Tools
+ *
+ * Tools exclusive to Planning LLM
+ * - create_todos: Create TODO list (when action/implementation needed)
+ * - respond_to_user: Direct response (for simple questions/conversation)
+ *
+ * Planning LLM must choose one of these two tools
+ */
+
+import { LLMSimpleTool, ToolResult } from '../../types.js';
+
+/**
+ * create_todos tool
+ * Create TODO list for tasks requiring planning
+ */
+export const createTodosTool: LLMSimpleTool = {
+  definition: {
+    type: 'function',
+    function: {
+      name: 'create_todos',
+      description: `Use this tool ONLY when the task requires code changes, file operations, or multi-step implementation work.
+
+When to use:
+- Code implementation tasks
+- Bug fixes
+- File modifications
+- Multi-step operations
+
+DO NOT use for:
+- Simple questions or explanations
+- Greetings or casual conversation
+- Clarifications that don't require code changes
+
+Guidelines:
+- 1-5 TODOs (even 1 is fine for simple actions!)
+- Actionable titles that clearly describe what to do
+- Sequential order (execution order)
+- Include details in title
+
+IMPORTANT: Write TODO titles in the user's language.`,
+      parameters: {
+        type: 'object',
+        properties: {
+          todos: {
+            type: 'array',
+            description: 'List of TODO items',
+            items: {
+              type: 'object',
+              properties: {
+                id: {
+                  type: 'string',
+                  description: 'Unique identifier (e.g., "1", "2", "3")',
+                },
+                title: {
+                  type: 'string',
+                  description: 'Clear, actionable task title (in user language)',
+                },
+              },
+              required: ['id', 'title'],
+            },
+          },
+          complexity: {
+            type: 'string',
+            enum: ['simple', 'moderate', 'complex'],
+            description: 'Estimated complexity of the overall task',
+          },
+        },
+        required: ['todos', 'complexity'],
+      },
+    },
+  },
+  // NOTE: This execute function is never called because PlanningLLM handles tool_call directly.
+  // It exists solely to provide tool definition.
+  execute: async (args: Record<string, unknown>): Promise<ToolResult> => {
+    const todos = args['todos'] as Array<{ id: string; title: string }>;
+    const complexity = args['complexity'] as string;
+    return {
+      success: true,
+      result: JSON.stringify({ todos, complexity }),
+    };
+  },
+  categories: ['llm-planning'],
+};
+
+/**
+ * respond_to_user tool
+ * Respond directly with text for simple questions or conversations
+ */
+export const respondToUserTool: LLMSimpleTool = {
+  definition: {
+    type: 'function',
+    function: {
+      name: 'respond_to_user',
+      description: `Use this tool when the user's request does NOT require any actions or code changes.
+
+When to use:
+- Pure knowledge questions (e.g., "What is a React hook?", "Explain async/await")
+- Greetings or casual conversation (e.g., "Hello", "How are you?")
+- Conceptual explanations that don't need code execution
+- Questions about general programming concepts
+
+DO NOT use for:
+- ANY task that requires code changes, file operations, or command execution
+- Bug fixes, implementation, refactoring, testing
+- Exploring codebase or searching files
+- Running commands or builds
+
+Guidelines:
+- Provide a clear, helpful response in the user's language
+- Keep explanations concise but complete
+- Use examples if helpful
+
+IMPORTANT: Write your response in the user's language.`,
+      parameters: {
+        type: 'object',
+        properties: {
+          response: {
+            type: 'string',
+            description: 'Your direct response to the user (in their language)',
+          },
+        },
+        required: ['response'],
+      },
+    },
+  },
+  execute: async (args: Record<string, unknown>): Promise<ToolResult> => {
+    const response = args['response'] as string;
+    return {
+      success: true,
+      result: response,
+    };
+  },
+  categories: ['llm-planning'],
+};
+
+/**
+ * All Planning tools
+ */
+export const PLANNING_TOOLS: LLMSimpleTool[] = [
+  createTodosTool,
+  respondToUserTool,
+];

package/src/tools/llm/simple/powershell-tool.ts

@@ -0,0 +1,241 @@
+/**
+ * PowerShell Tool (Native Windows Only)
+ *
+ * Tool that allows LLM to execute PowerShell commands
+ * Only registered in Native Windows environments
+ */
+
+import { spawn } from 'child_process';
+import * as fs from 'fs';
+import { ToolDefinition } from '../../../types/index.js';
+import { LLMSimpleTool, ToolResult, ToolCategory } from '../../types.js';
+import { logger } from '../../../utils/logger.js';
+import {
+  isNativeWindows,
+  findNativePowerShellPath,
+  isDangerousPowerShellCommand,
+} from '../../../utils/platform-utils.js';
+import { filterSafeEnv } from '../../../utils/env-filter.js';
+import { configManager } from '../../../core/config/config-manager.js';
+
+/**
+ * Execute PowerShell command
+ */
+async function executePowerShell(
+  command: string,
+  cwd?: string,
+  timeout: number = 30000,
+  explicitEnv?: Record<string, string>
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  return new Promise((resolve, reject) => {
+    const psPath = findNativePowerShellPath();
+
+    // Get user-configured safe env vars
+    const userSafeVars = configManager.getSafeEnvVars();
+
+    // Use -NoProfile for faster startup, -Command for direct execution
+    const child = spawn(psPath, ['-NoProfile', '-Command', command], {
+      cwd: cwd || process.cwd(),
+      env: filterSafeEnv(process.env, userSafeVars, explicitEnv || {}), // Merge: filtered process.env + user config + explicit vars
+    });
+
+    let stdout = '';
+    let stderr = '';
+    let killed = false;
+
+    child.stdout?.on('data', (data) => {
+      stdout += data.toString();
+    });
+
+    child.stderr?.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    child.on('close', (code) => {
+      if (!killed) {
+        resolve({
+          stdout: stdout.trim(),
+          stderr: stderr.trim(),
+          exitCode: code ?? 0,
+        });
+      }
+    });
+
+    child.on('error', (error) => {
+      reject(error);
+    });
+
+    // Timeout handling
+    const timer = setTimeout(() => {
+      killed = true;
+      child.kill('SIGTERM');
+      reject(new Error(`Command timed out after ${timeout}ms`));
+    }, timeout);
+
+    child.on('close', () => {
+      clearTimeout(timer);
+    });
+  });
+}
+
+/**
+ * PowerShell Tool Definition
+ */
+const POWERSHELL_TOOL_DEFINITION: ToolDefinition = {
+  type: 'function',
+  function: {
+    name: 'powershell',
+    description: `Execute a PowerShell command on Windows. Use this to run terminal commands like git, npm, docker, python, etc.
+
+IMPORTANT:
+- Do NOT use for file reading/writing - use read_file, create_file, edit_file instead
+- Commands have a 30 second timeout by default
+- Dangerous commands (Remove-Item -Recurse -Force C:\\, Stop-Computer, etc.) are blocked
+- Output is truncated if too long
+- PowerShell 7 (pwsh) is used if available, otherwise PowerShell 5.1`,
+    parameters: {
+      type: 'object',
+      properties: {
+        reason: {
+          type: 'string',
+          description: `A natural, conversational explanation for the user about what you're doing (in user's language).
+Write as if you're talking to the user directly.
+Examples:
+- "Installing project dependencies"
+- "Running tests to check the results"
+- "Checking git status"
+- "Running the build"`,
+        },
+        command: {
+          type: 'string',
+          description: 'The PowerShell command to execute',
+        },
+        cwd: {
+          type: 'string',
+          description: 'Working directory for the command (optional, defaults to current directory)',
+        },
+        timeout: {
+          type: 'number',
+          description: 'Timeout in milliseconds (optional, default: 30000)',
+        },
+        env: {
+          type: 'object',
+          description: 'Environment variables to set for this command (optional). These will be merged with safe system env vars.',
+          additionalProperties: {
+            type: 'string',
+          },
+        },
+      },
+      required: ['reason', 'command'],
+    },
+  },
+};
+
+/**
+ * PowerShell Tool (LLM Simple)
+ */
+export const powershellTool: LLMSimpleTool = {
+  definition: POWERSHELL_TOOL_DEFINITION,
+  categories: ['llm-simple'] as ToolCategory[],
+
+  async execute(args: Record<string, unknown>): Promise<ToolResult> {
+    const command = args['command'] as string;
+    const cwd = args['cwd'] as string | undefined;
+    const timeout = (args['timeout'] as number) || 30000;
+    const env = args['env'] as Record<string, string> | undefined;
+
+    logger.enter('powershellTool.execute', { command, cwd, timeout, envKeys: env ? Object.keys(env) : [] });
+
+    // Check platform - should only run on Native Windows
+    if (!isNativeWindows()) {
+      return {
+        success: false,
+        error: 'powershell tool is only available on Native Windows. Use bash instead.',
+      };
+    }
+
+    // Validate command
+    if (!command || typeof command !== 'string') {
+      return {
+        success: false,
+        error: 'command is required and must be a string',
+      };
+    }
+
+    // Check for dangerous commands
+    if (isDangerousPowerShellCommand(command)) {
+      logger.warn('Dangerous PowerShell command blocked', { command });
+      return {
+        success: false,
+        error: 'This command is blocked for safety reasons',
+      };
+    }
+
+    // Validate cwd exists and is a directory
+    if (cwd) {
+      if (!fs.existsSync(cwd)) {
+        logger.warn('Invalid cwd provided (does not exist)', { cwd });
+        return {
+          success: false,
+          error: `Working directory does not exist: ${cwd}`,
+        };
+      }
+      if (!fs.statSync(cwd).isDirectory()) {
+        logger.warn('Invalid cwd provided (not a directory)', { cwd });
+        return {
+          success: false,
+          error: `Working directory path is not a directory: ${cwd}`,
+        };
+      }
+    }
+
+    try {
+      const execResult = await executePowerShell(command, cwd, timeout, env);
+
+      // Combine output
+      let output = '';
+      if (execResult.stdout) {
+        output += execResult.stdout;
+      }
+      if (execResult.stderr) {
+        output += (output ? '\n\n' : '') + `stderr:\n${execResult.stderr}`;
+      }
+
+      // Truncate if too long
+      const MAX_OUTPUT_LENGTH = 50000;
+      if (output.length > MAX_OUTPUT_LENGTH) {
+        output = output.slice(0, MAX_OUTPUT_LENGTH) + '\n\n... [output truncated]';
+      }
+
+      // Add exit code if non-zero
+      if (execResult.exitCode !== 0) {
+        output += `\n\n[Exit code: ${execResult.exitCode}]`;
+      }
+
+      logger.exit('powershellTool.execute', { exitCode: execResult.exitCode, outputLength: output.length });
+
+      // Return with error field when command fails
+      if (execResult.exitCode !== 0) {
+        return {
+          success: false,
+          error: output || '(no output)',
+        };
+      }
+
+      return {
+        success: true,
+        result: output || '(no output)',
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      logger.error('powershellTool.execute failed', error as Error);
+
+      return {
+        success: false,
+        error: `Error executing command: ${errorMessage}`,
+      };
+    }
+  },
+};
+
+export default powershellTool;