onbuzz 3.3.0

package/src/tools/jobDoneTool.js

@@ -0,0 +1,388 @@
+/**
+ * Job Done Tool - Signals task completion in autonomous mode
+ * 
+ * Purpose:
+ * - Allow agents to explicitly signal when a task is complete
+ * - Provide completion summary/reason
+ * - Gracefully exit autonomous mode
+ * - Return to chat mode (unless in locked mode)
+ */
+
+import { BaseTool } from './baseTool.js';
+import TagParser from '../utilities/tagParser.js';
+
+class JobDoneTool extends BaseTool {
+  constructor() {
+    super();
+    this.id = 'jobdone';
+    this.name = 'Job Done';
+    this.description = 'Call this tool when you have successfully completed the assigned task, OR if you are stuck/unable to proceed after multiple failed attempts. Provide a summary of what was accomplished or what prevented completion. This will exit autonomous mode and return control to the user.';
+    this.version = '1.0.0';
+    this.capabilities = ['task-completion', 'mode-control'];
+    this.requiresProject = false;
+    this.async = false;
+  }
+
+  /**
+   * Get tool description for LLM consumption
+   * @returns {string} Tool description
+   */
+  getDescription() {
+    return `
+Job Done Tool: Signal task completion in autonomous mode and exit to chat mode.
+
+USAGE:
+\`\`\`json
+{
+  "toolId": "jobdone",
+  "actions": [{
+    "action": "complete",
+    "summary": "Task completion summary",
+    "success": true,
+    "details": "Optional additional details"
+  }]
+}
+\`\`\`
+
+PARAMETERS:
+- action: Always "complete"
+- summary: Clear summary of what was accomplished OR what prevented completion (required)
+- success: true if completed successfully, false if stuck/failed (default: true)
+- details: Optional additional information about the task
+
+EXAMPLES:
+
+1. Successful completion:
+\`\`\`json
+{
+  "toolId": "jobdone",
+  "actions": [{
+    "action": "complete",
+    "summary": "Created 5 song files successfully with lyrics and melodies",
+    "success": true
+  }]
+}
+\`\`\`
+
+2. Unable to proceed:
+\`\`\`json
+{
+  "toolId": "jobdone",
+  "actions": [{
+    "action": "complete",
+    "summary": "Unable to proceed: missing API credentials for the service",
+    "success": false
+  }]
+}
+\`\`\`
+
+3. Partial completion:
+\`\`\`json
+{
+  "toolId": "jobdone",
+  "actions": [{
+    "action": "complete",
+    "summary": "Task partially complete: implemented 2 of 3 requested features",
+    "success": false,
+    "details": "The third feature requires additional dependencies not available"
+  }]
+}
+\`\`\`
+
+WHEN TO USE:
+- Call when you have SUCCESSFULLY completed the assigned task
+- Call if you are STUCK or UNABLE to proceed after multiple failed attempts
+- This will immediately exit autonomous mode and return control to the user
+
+IMPORTANT - COMPLETION TIMING: - Call this tool IMMEDIATELY when your task is complete, Multiple jobdone calls per conversation are EXPECTED and CORRECT - Each discrete task = one jobdone call If user requests additional work after jobdone: 1. That's a NEW task, Complete the new task then Call jobdone again
+    `.trim();
+  }
+
+  /**
+   * Parse parameters from tool command content
+   * @param {string} content - Raw tool command content
+   * @returns {Object} Parsed parameters object
+   */
+  parseParameters(content) {
+    try {
+      // For JobDoneTool, we expect the content to be structured with tags
+      // or we can parse it as a simple completion message
+      
+      // Try to extract structured content first
+      const summaryMatches = TagParser.extractContent(content, 'summary');
+      const detailsMatches = TagParser.extractContent(content, 'details');
+      const successMatches = TagParser.extractContent(content, 'success');
+      
+      let summary = '';
+      let details = '';
+      let success = true;
+      
+      if (summaryMatches.length > 0) {
+        // Structured format with tags
+        summary = summaryMatches[0].trim();
+        details = detailsMatches.length > 0 ? detailsMatches[0].trim() : '';
+        success = successMatches.length > 0 ? (successMatches[0].toLowerCase() !== 'false') : true;
+      } else {
+        // Fallback: use the entire content as summary
+        summary = content.trim() || 'Task completed';
+      }
+      
+      return {
+        actions: [{
+          action: 'complete',
+          summary: summary,
+          success: success,
+          details: details || undefined
+        }]
+      };
+      
+    } catch (error) {
+      // Fallback to simple parsing
+      return {
+        actions: [{
+          action: 'complete',
+          summary: content.trim() || 'Task completed',
+          success: true
+        }]
+      };
+    }
+  }
+
+  /**
+   * Get tool schema for AI model
+   * @returns {Object} Tool schema
+   */
+  getSchema() {
+    return {
+      type: 'object',
+      properties: {
+        actions: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              action: {
+                type: 'string',
+                enum: ['complete'],
+                description: 'Mark task as complete - always use "complete"'
+              },
+              summary: {
+                type: 'string',
+                description: 'Clear summary of what you accomplished OR what prevented completion (e.g., "Created 5 song files successfully", "Unable to proceed: missing API credentials", "Stuck after 3 failed compilation attempts")'
+              },
+              success: {
+                type: 'boolean',
+                default: true,
+                description: 'Set to true if task completed successfully, false if stuck/failed or partial completion'
+              },
+              details: {
+                type: 'string',
+                description: 'Optional: Additional details about what was done, what failed, any files created, or next steps for the user'
+              }
+            },
+            required: ['action', 'summary'],
+            additionalProperties: false
+          },
+          minItems: 1,
+          maxItems: 1
+        }
+      },
+      required: ['actions'],
+      additionalProperties: false
+    };
+  }
+
+  /**
+   * Execute job done action
+   * @param {Object} parameters - Tool parameters
+   * @param {Object} context - Execution context
+   * @returns {Promise<Object>} Execution result
+   */
+  async execute(parameters, context = {}) {
+    try {
+      const { actions } = parameters;
+      
+      if (!actions || !Array.isArray(actions) || actions.length === 0) {
+        throw new Error('Actions array is required');
+      }
+
+      const action = actions[0];
+      
+      if (action.action !== 'complete') {
+        throw new Error('Invalid action. Only "complete" is supported');
+      }
+
+      if (!action.summary) {
+        throw new Error('Completion summary is required');
+      }
+
+      const agentId = context.agentId;
+      let agent = null;
+      let agentInfo = '';
+
+      if (agentId && this.agentPool) {
+        try {
+          agent = await this.agentPool.getAgent(agentId);
+          if (agent) {
+            agentInfo = ` by agent "${agent.name}"`;
+          }
+        } catch (error) {
+          // Ignore agent info errors
+        }
+      }
+
+      // Check for pending/in-progress tasks
+      const pendingTasks = agent?.taskList?.tasks?.filter(
+        t => t.status === 'pending' || t.status === 'in_progress'
+      ) || [];
+
+      // If there are pending tasks and the agent claims success, reject.
+      // The agent must clear/complete its task list first.
+      // Exception: success=false means the agent is giving up (stuck/unable to proceed).
+      if (pendingTasks.length > 0 && action.success !== false) {
+        const taskListStr = pendingTasks
+          .map((t, i) => `${i + 1}. [${t.status}] ${t.title}`)
+          .join('\n');
+
+        this.logger?.info(`JobDone: Rejected - agent ${agentId} has ${pendingTasks.length} pending tasks`, {
+          pendingTasks: pendingTasks.length
+        });
+
+        return {
+          success: false,
+          output: `Cannot mark job as done — you still have ${pendingTasks.length} pending task(s):\n${taskListStr}\n\nComplete or cancel all tasks before calling job-done, or call job-done with success=false if you are unable to proceed.`,
+          taskComplete: false,
+          pendingTasks: pendingTasks.length
+        };
+      }
+
+      // Format completion message
+      const isSuccessful = action.success !== false;
+      const completionMessage = `${isSuccessful ? '✅' : '⚠️'} Task completed${agentInfo}${isSuccessful ? ' successfully' : ' with issues'}
+
+**Summary:** ${action.summary}${action.details ? `
+
+**Details:** ${action.details}` : ''}
+
+*All tasks cleared. Agent remains in agent mode, ready for new work.*`;
+
+      // Clear the task list — agent becomes idle with no pending work.
+      // Scheduler condition: has pending tasks AND in agent mode.
+      // New messages will auto-create tasks and reactivate the agent.
+      if (agent) {
+        try {
+          const sessionId = agent.sessionId;
+          const clearedTaskCount = agent.taskList?.tasks?.length || 0;
+
+          if (agent.taskList) {
+            agent.taskList.tasks = [];
+            agent.taskList.lastUpdated = new Date().toISOString();
+          }
+
+          agent.autonomousWorkComplete = true;
+          agent.lastCompletionSummary = action.summary;
+          agent.lastCompletionDetails = action.details || null;
+          await this.agentPool.persistAgentState(agentId);
+
+          // Signal flow executor directly (if agent is running inside a flow)
+          if (this.flowExecutor) {
+            this.flowExecutor.notifyAgentCompletion(agentId, {
+              summary: action.summary,
+              details: action.details,
+              success: isSuccessful
+            });
+          }
+
+          this.logger?.info(`JobDone: Agent ${agentId} tasks cleared, staying in AGENT mode`, {
+            clearedTaskCount,
+            summary: action.summary,
+            success: isSuccessful
+          });
+
+          if (this.webSocketManager && sessionId) {
+            this.webSocketManager.broadcastToSession(sessionId, {
+              type: 'agent_job_done',
+              data: {
+                agentId,
+                mode: agent.mode,
+                clearedTaskCount,
+                reason: 'jobdone',
+                timestamp: new Date().toISOString()
+              }
+            });
+          }
+        } catch (error) {
+          this.logger?.warn(`JobDone: Failed to clear agent tasks`, { error: error.message });
+        }
+      }
+
+      return {
+        success: true,
+        output: completionMessage,
+        taskComplete: true,
+        exitAutonomousMode: true,
+        summary: action.summary,
+        details: action.details || null,
+        successfulCompletion: isSuccessful,
+        metadata: {
+          toolId: this.id,
+          agentId: agentId || 'unknown',
+          completedAt: new Date().toISOString(),
+          action: action.action
+        }
+      };
+      
+    } catch (error) {
+      return {
+        success: false,
+        error: error.message,
+        output: `Failed to mark task as complete: ${error.message}`,
+        taskComplete: false
+      };
+    }
+  }
+
+  /**
+   * Set AgentPool dependency for agent information
+   * @param {AgentPool} agentPool - AgentPool instance
+   */
+  setAgentPool(agentPool) {
+    this.agentPool = agentPool;
+  }
+
+  /**
+   * Set WebSocketManager dependency for broadcasting mode changes
+   * @param {WebSocketManager} webSocketManager - WebSocketManager instance
+   */
+  setWebSocketManager(webSocketManager) {
+    this.webSocketManager = webSocketManager;
+  }
+
+  /**
+   * Set FlowExecutor dependency for direct completion signaling
+   * @param {FlowExecutor} flowExecutor - FlowExecutor instance
+   */
+  setFlowExecutor(flowExecutor) {
+    this.flowExecutor = flowExecutor;
+  }
+
+  /**
+   * Get tool capabilities
+   * @returns {Object} Tool capabilities
+   */
+  getCapabilities() {
+    return {
+      id: this.id,
+      name: this.name,
+      description: this.description,
+      version: this.version,
+      capabilities: this.capabilities,
+      requiresProject: this.requiresProject,
+      async: this.async,
+      enabled: true,
+      schema: this.getSchema()
+    };
+  }
+}
+
+export default JobDoneTool;