𓂀𓁢𓋹𝔸ℕ𝕌𝔹𝕀𝕊𓋹𓁢𓂀 - Intelligent Guidance for

Instructions

Implementation Reference

• src/domains/workflow-rules/mcp-operations/step-execution-mcp.service.ts:273-315 (handler)

  The @Tool-decorated handler function implementing the report_step_completion MCP tool logic. Processes input, validates executionId, delegates to StepExecutionService.processStepCompletion, and returns structured response.

  @Tool({
    name: 'report_step_completion',
    description: `Report step completion results with structured data and get next step guidance.`,
    parameters:
      ReportStepCompletionInputSchema as ZodSchema<ReportStepCompletionInput>,
  })
  async reportStepCompletion(input: ReportStepCompletionInput) {
    try {
      // Final validation - we must have an executionId at this point
      if (!input.executionId) {
        return this.buildErrorResponse(
          'No execution identifier provided',
          'Either taskId or executionId must be provided',
          'MISSING_EXECUTION_ID',
        );
      }
  
      // ✅ DELEGATE to StepExecutionService with structured data
      const completionResult =
        await this.stepExecutionService.processStepCompletion(
          input.executionId,
          input.stepId,
          input.result,
          input.executionData,
          input.validationResults,
          input.reportData,
        );
  
      return this.buildResponse({
        success: true,
        message: `Step '${input.stepId}' completion reported successfully`,
        result: input.result,
        hasNextStep: Boolean(completionResult?.nextStep),
        nextStepAvailable: completionResult?.nextStep ? true : false,
      });
    } catch (error) {
      return this.buildErrorResponse(
        'Failed to report step completion',
        getErrorMessage(error),
        'STEP_COMPLETION_ERROR',
      );
    }
  }

• src/domains/workflow-rules/mcp-operations/step-execution-mcp.service.ts:41-116 (schema)

  Input schema validation using Zod for the report_step_completion tool parameters, including execution details, results, and optional data.

  const ReportStepCompletionInputSchema = z
    .object({
      taskId: z
        .number()
        .optional()
        .describe('Task ID (optional if executionId provided)'),
      executionId: z.string().describe('Execution ID'),
      stepId: z.string().describe('Completed step ID'),
      result: z.enum(['success', 'failure']).describe('Execution result'),
      executionTime: z.number().optional().describe('Execution time in ms'),
  
      // ✅ MINIMAL: Only actually used fields based on analysis
      executionData: z
        .object({
          // Core fields - most commonly used
          outputSummary: z
            .string()
            .optional()
            .describe('Brief summary of what was accomplished'),
          filesModified: z
            .array(z.string())
            .optional()
            .describe('List of files that were modified'),
          commandsExecuted: z
            .array(z.string())
            .optional()
            .describe('List of commands that were executed'),
  
          // Quality validation - simple boolean
          qualityChecksComplete: z
            .boolean()
            .optional()
            .describe('Whether quality checks were completed'),
  
          // Optional implementation details
          implementationSummary: z
            .string()
            .optional()
            .describe('Summary of implementation approach taken'),
        })
        .optional()
        .describe('Essential execution data'),
  
      // ✅ MINIMAL: Basic validation results
      validationResults: z
        .object({
          allChecksPassed: z
            .boolean()
            .describe('Whether all validation checks passed'),
          issues: z.array(z.string()).optional().describe('List of issues found'),
        })
        .optional()
        .describe('Basic validation results'),
  
      // ✅ MINIMAL: Optional report data for advanced tracking
      reportData: z
        .object({
          stepType: z
            .string()
            .optional()
            .describe('Type of step that was completed'),
          keyAchievements: z
            .array(z.string())
            .optional()
            .describe('Key achievements in this step'),
        })
        .optional()
        .describe('Optional report data'),
    })
    .refine(
      (data) => data.taskId !== undefined || data.executionId !== undefined,
      {
        message: 'Either taskId or executionId must be provided',
        path: ['taskId', 'executionId'],
      },
    );

• src/domains/workflow-rules/mcp-operations/step-execution-mcp.service.ts:273-278 (registration)

  Tool registration via @Tool decorator specifying name, description, and schema.

  @Tool({
    name: 'report_step_completion',
    description: `Report step completion results with structured data and get next step guidance.`,
    parameters:
      ReportStepCompletionInputSchema as ZodSchema<ReportStepCompletionInput>,
  })