@koi-language/koi 1.0.5 → 1.1.0

package/src/runtime/actions/shell.js

@@ -0,0 +1,185 @@
+/**
+ * Shell Action - Execute a shell command with user permission.
+ *
+ * The LLM must provide a human-readable description of what the command does.
+ * Before execution, the user is prompted for permission unless the command
+ * has been "Always allow"-ed for this agent during the current session.
+ *
+ * Permission options:
+ *   - Yes            → execute this time only
+ *   - Always allow   → execute without asking again (this agent, this session)
+ *   - No             → skip this time (can be asked again later)
+ *
+ * Permissions are per-agent and in-memory only (reset between sessions).
+ */
+
+import { spawn } from 'child_process';
+import { cliLogger } from '../cli-logger.js';
+import { cliSelect } from '../cli-select.js';
+
+async function askPermission(command, description) {
+  cliLogger.clearProgress();
+
+  process.stdout.write(`\n${description}\n`);
+  process.stdout.write(`🔧 The agent wants to execute this command:\n`);
+  process.stdout.write(`   \x1b[33m$ ${command}\x1b[0m\n\n`);
+
+  const value = await cliSelect('Allow this command?', [
+    { title: 'Yes', value: 'yes', description: 'Execute this time' },
+    { title: 'Always allow', value: 'always', description: 'Always allow for this agent (this session only)' },
+    { title: 'No', value: 'no', description: 'Skip this command' }
+  ]);
+
+  return value || 'no';
+}
+
+export default {
+  type: 'shell',
+  intent: 'shell',
+  description: 'Execute a shell command (requires user permission). Requires: command (the shell command), description (human-friendly explanation of what it does and why). Optional: cwd (working directory)',
+  permission: 'execute',
+  hidden: false,
+
+  schema: {
+    type: 'object',
+    properties: {
+      command: { type: 'string', description: 'The shell command to execute' },
+      description: { type: 'string', description: 'Human-friendly reason WHY this command is needed (shown to user). Express NEED, not action. Good: "Need to install X because Y". Bad: "Installing X".' },
+      cwd: { type: 'string', description: 'Working directory for the command (optional)' }
+    },
+    required: ['command', 'description']
+  },
+
+  examples: [
+    {
+      actionType: 'direct',
+      intent: 'shell',
+      command: 'npm install',
+      description: 'Need to install Node.js dependencies required by the project',
+      cwd: '/path/to/project'
+    },
+    {
+      actionType: 'direct',
+      intent: 'shell',
+      command: 'brew tap facebook/fb && brew install idb-companion && pip install fb-idb',
+      description: 'Need to install IDB because the MCP server requires it for iOS Simulator control'
+    }
+  ],
+
+  async execute(action, agent) {
+    const { command, description, cwd } = action;
+
+    if (!command) {
+      throw new Error('shell: "command" field is required');
+    }
+    if (!description) {
+      throw new Error('shell: "description" field is required');
+    }
+
+    // Reject commands with obvious placeholder values like <your_api_key>, <TOKEN>, etc.
+    const placeholderMatch = command.match(/<[a-zA-Z_][a-zA-Z0-9_]*>/);
+    if (placeholderMatch) {
+      return {
+        success: false,
+        error: `Command contains a placeholder "${placeholderMatch[0]}" instead of a real value. Do NOT use placeholder values — use actual values or ask the user for them with prompt_user.`
+      };
+    }
+
+    // Per-agent in-memory allowed commands (lazy-init on the agent instance)
+    if (!agent._allowedShellCommands) {
+      agent._allowedShellCommands = new Set();
+    }
+
+    let permitted = agent._allowedShellCommands.has(command);
+
+    if (permitted) {
+      process.stdout.write(`\n${description}\n`);
+      process.stdout.write(`⚡ Executing: \x1b[33m$ ${command}\x1b[0m\n`);
+    } else {
+      // Ask user for permission
+      const answer = await askPermission(command, description);
+
+      if (answer === 'always') {
+        agent._allowedShellCommands.add(command);
+        permitted = true;
+      } else if (answer === 'yes') {
+        permitted = true;
+      }
+    }
+
+    if (!permitted) {
+      console.log(`   ⏭️  Skipped`);
+      return {
+        success: false,
+        denied: true,
+        message: `User denied execution: ${description}`
+      };
+    }
+
+    return new Promise((resolve) => {
+      const child = spawn('sh', ['-c', command], {
+        cwd: cwd || process.cwd(),
+        env: { ...process.env },
+        stdio: ['inherit', 'pipe', 'pipe'] // stdin from user (for sudo etc), capture stdout/stderr
+      });
+
+      const stdoutChunks = [];
+      const stderrChunks = [];
+
+      child.stdout.on('data', (data) => {
+        stdoutChunks.push(data);
+        // Stream stdout to console in real-time
+        process.stdout.write(data);
+      });
+
+      child.stderr.on('data', (data) => {
+        stderrChunks.push(data);
+        // Stream stderr to console in real-time
+        process.stderr.write(data);
+      });
+
+      // Timeout after 5 minutes
+      const timeout = setTimeout(() => {
+        child.kill('SIGTERM');
+      }, 300000);
+
+      child.on('close', (code) => {
+        clearTimeout(timeout);
+
+        const stdoutStr = Buffer.concat(stdoutChunks).toString().trim();
+        const stderrStr = Buffer.concat(stderrChunks).toString().trim();
+
+        if (code !== 0) {
+          console.log(`   ❌ Failed (exit code ${code})`);
+          resolve({
+            success: false,
+            exitCode: code || 1,
+            stdout: stdoutStr,
+            stderr: stderrStr,
+            error: stderrStr || `Command exited with code ${code}`
+          });
+        } else {
+          console.log(`   ✅ Done`);
+          resolve({
+            success: true,
+            exitCode: 0,
+            stdout: stdoutStr,
+            stderr: stderrStr
+          });
+        }
+      });
+
+      child.on('error', (err) => {
+        clearTimeout(timeout);
+        console.log(`   ❌ Failed: ${err.message}`);
+        resolve({
+          success: false,
+          exitCode: 1,
+          stdout: '',
+          stderr: '',
+          error: err.message
+        });
+      });
+    });
+  }
+};

package/src/runtime/actions/while.js

@@ -0,0 +1,205 @@
+/**
+ * While Action - Execute actions at least once, then repeat while condition is true (do-while semantics)
+ */
+import { buildActionDisplay } from '../cli-display.js';
+
+export default {
+  type: 'while',
+  intent: 'while',
+  description: 'Execute actions at least once, then repeat while condition is true. CONDITION: Use string "${a1.output} !== \'stop\'" for exact match, OR object with llm_eval for semantic: { "llm_eval": true, "instruction": "¿Continuar? (false si despide)", "data": "${a1.output.answer}" } → Returns: { iterations: N, results: [array], stopped_reason: "condition_false" | "max_iterations" }',
+  permission: 'execute',
+
+  schema: {
+    type: 'object',
+    properties: {
+      condition: {
+        oneOf: [
+          { type: 'string', description: 'Simple condition (e.g., "${a1.output.answer} !== \'hasta luego\'")' },
+          { type: 'object', description: 'LLM-evaluated condition with llm_eval: true, instruction, and data fields' }
+        ]
+      },
+      actions: {
+        type: 'array',
+        description: 'Actions to execute in each iteration'
+      },
+      max_iterations: {
+        type: 'number',
+        description: 'Optional safety limit to prevent infinite loops (default: 100)'
+      }
+    },
+    required: ['condition', 'actions']
+  },
+
+  examples: [
+    {
+      intent: 'while',
+      condition: "${a1.output.answer} !== 'hasta luego'",
+      max_iterations: 10,
+      actions: [
+        { id: 'a1', intent: 'prompt_user', question: '¿Qué quieres hablar? (escribe "hasta luego" para salir)' },
+        { intent: 'print', message: 'Dijiste: ${a1.output.answer}' }
+      ]
+    }
+  ],
+
+  // Executor function
+  async execute(action, agent) {
+    const condition = action.condition || action.data?.condition || '';
+    const actions = action.actions || action.data?.actions || [];
+    const maxIterations = action.max_iterations || action.data?.max_iterations || 100;
+
+    if (!condition) {
+      throw new Error('while action requires a "condition" field');
+    }
+
+    if (!actions || actions.length === 0) {
+      throw new Error('while action requires an "actions" array');
+    }
+
+    // Get the current action context from the agent
+    const context = agent._currentActionContext || {
+      state: agent.state,
+      results: []
+    };
+
+    // Execute actions with inherited context
+    const actionRegistry = (await import('../action-registry.js')).actionRegistry;
+    const cliLogger = (await import('../cli-logger.js')).cliLogger;
+
+    const allResults = [];
+    let iterations = 0;
+    let stoppedReason = 'condition_false';
+
+    // Do-while loop: execute at least once, then check condition
+    while (iterations < maxIterations) {
+      iterations++;
+
+      // Create iteration context with current iteration number
+      const iterationContext = {
+        ...context,
+        iteration: iterations,
+        iterationIndex: iterations - 1
+      };
+
+      // Execute actions first
+      for (const nestedAction of actions) {
+        // Resolve references using the iteration context
+        const resolvedAction = agent.resolveActionReferences(nestedAction, iterationContext);
+
+        // Show progress
+        cliLogger.planning(buildActionDisplay(agent.name, resolvedAction));
+
+        let result;
+
+        // Check if this is a delegation action
+        if (resolvedAction.actionType === 'delegate') {
+          // Delegation: route to appropriate team member
+          result = await agent.resolveAction(resolvedAction, iterationContext);
+        } else {
+          // Direct action: Get action definition from registry
+          const actionDef = actionRegistry.get(nestedAction.intent || nestedAction.type);
+
+          if (actionDef && actionDef.execute) {
+            // Update agent's current context for nested action
+            const previousContext = agent._currentActionContext;
+            agent._currentActionContext = iterationContext;
+
+            // Execute with agent
+            result = await actionDef.execute(resolvedAction, agent);
+
+            // Restore previous context
+            agent._currentActionContext = previousContext;
+          } else {
+            cliLogger.clear();
+            throw new Error(`Action ${nestedAction.intent || nestedAction.type} not found`);
+          }
+        }
+
+        cliLogger.clear();
+
+        // Update iteration context with result (and parent context for next iteration's condition check)
+        if (result && typeof result === 'object') {
+          // Unwrap double-encoded results (LLM sometimes returns { "result": "{...json...}" })
+          if (result.result && typeof result.result === 'string' && Object.keys(result).length === 1) {
+            try {
+              const parsed = JSON.parse(result.result);
+              if (typeof parsed === 'object') {
+                result = parsed;
+              }
+            } catch (e) {
+              // Not JSON, keep as-is
+            }
+          }
+
+          const resultForContext = JSON.parse(JSON.stringify(result));
+          iterationContext.results.push(resultForContext);
+          context.results.push(resultForContext);  // Also update parent for condition evaluation
+
+          // Store with action ID if provided
+          if (nestedAction.id) {
+            iterationContext[nestedAction.id] = { output: resultForContext };
+            context[nestedAction.id] = { output: resultForContext };  // Also update parent
+          }
+
+          // Track all results
+          allResults.push(resultForContext);
+        }
+      }
+
+      // After executing actions, evaluate condition to decide if we should continue
+      let conditionResult = false;
+      try {
+        // Check if condition is LLM-evaluated (object with llm_eval: true)
+        if (typeof condition === 'object' && condition.llm_eval === true) {
+          // Show progress while evaluating condition
+          const displayText = condition.desc ? condition.desc.replace(/\.\.\.$/, '') : 'Evaluating condition';
+          cliLogger.planning(`[🤖 ${agent.name}] ${displayText}`);
+
+          // Use call_llm action to evaluate condition with LLM
+          const callLlmAction = (await import('./call-llm.js')).default;
+
+          // Resolve data references
+          const resolvedData = agent.resolveObjectReferences(condition.data || {}, context);
+
+          // Create call_llm action to evaluate condition
+          const callLlmRequest = {
+            data: resolvedData,
+            instruction: condition.instruction + "\n\nRESPOND WITH ONLY 'true' or 'false' (lowercase, no quotes, no explanation)."
+          };
+
+          const llmResult = await callLlmAction.execute(callLlmRequest, agent);
+          const resultText = llmResult.result.trim().toLowerCase();
+
+          // Clear progress
+          cliLogger.clear();
+
+          // Parse boolean result
+          conditionResult = resultText === 'true';
+        } else {
+          // Simple string condition - evaluate with JavaScript
+          conditionResult = agent.evaluateCondition(condition, context);
+        }
+      } catch (error) {
+        throw new Error(`Failed to evaluate while condition: ${error.message}`);
+      }
+
+      // If condition is false, stop (don't continue to next iteration)
+      if (!conditionResult) {
+        stoppedReason = 'condition_false';
+        break;
+      }
+
+      // Safety check
+      if (iterations >= maxIterations) {
+        stoppedReason = 'max_iterations';
+        break;
+      }
+    }
+
+    return {
+      iterations,
+      results: allResults,
+      stopped_reason: stoppedReason
+    };
+  }
+};