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

Instructions

Implementation Reference

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

  The main handler function for the 'get_step_progress' MCP tool. It fetches execution details, step progress records, computes progress metrics, and returns a structured response with current step status, progress percentage, and summary of last completed step.

  async getStepProgress(input: GetStepProgressInput) {
    try {
      // ✅ CRITICAL FIX: Use executionId for progress tracking instead of taskId
      const executionResult =
        await this.workflowExecutionOperationsService.getExecution({
          executionId: input.executionId,
        });
  
      if (!executionResult.execution) {
        return this.buildResponse({
          executionId: input.executionId,
          status: 'no_execution',
          error: 'No execution found for provided executionId',
        });
      }
  
      const execution = executionResult.execution;
  
      // Get only essential step progress data
      const stepProgressRepository =
        this.stepExecutionService['stepProgressRepository'];
      const stepProgressRecords =
        await stepProgressRepository.findByExecutionId(input.executionId);
  
      // Count completed steps and get most recent
      const completedSteps = stepProgressRecords.filter(
        (record) => record.status === 'COMPLETED',
      );
      const mostRecentStep = completedSteps[0] || null;
  
      const currentStep = execution.currentStep;
      const currentRole = execution.currentRole;
  
      return this.buildResponse({
        executionId: input.executionId,
        taskId: execution.taskId,
        status: execution.completedAt ? 'completed' : 'in_progress',
  
        // Current execution state
        currentStep: {
          id: currentStep?.id,
          name: currentStep?.name || 'No current step',
          status: execution.completedAt ? 'completed' : 'active',
          roleId: execution.currentRoleId,
          roleName: currentRole?.name || 'Unknown',
        },
  
        // Essential progress metrics
        progress: {
          stepsCompleted:
            completedSteps.length || execution.stepsCompleted || 0,
          progressPercentage: execution.progressPercentage || 0,
          totalSteps: execution.totalSteps || 0,
        },
  
        // Minimal execution context
        executionContext: {
          phase: (execution.executionState as any)?.phase || 'unknown',
          executionMode: execution.executionMode,
          startedAt: execution.startedAt,
          completedAt: execution.completedAt,
        },
  
        // Essential summary only
        summary: {
          totalStepsCompleted: completedSteps.length,
          lastCompletedStep: mostRecentStep
            ? {
                stepName: mostRecentStep.step?.name || 'Unknown',
                roleName: mostRecentStep.role?.name || 'Unknown',
                completedAt: mostRecentStep.completedAt,
                summary:
                  (mostRecentStep.executionData as any)?.outputSummary ||
                  'No summary available',
              }
            : null,
          isReady: Boolean(currentStep && !execution.completedAt),
        },
      });
    } catch (error) {
      return this.buildErrorResponse(
        'Failed to get step progress',
        getErrorMessage(error),
        'STEP_PROGRESS_ERROR',
      );
    }
  }

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

  Registration of the 'get_step_progress' tool using the @Tool decorator, specifying name, description, and input schema.

  @Tool({
    name: 'get_step_progress',
    description: `Get concise step progress focused on essential status information for workflow continuation.`,
    parameters: GetStepProgressInputSchema as ZodSchema<GetStepProgressInput>,
  })

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

  Zod schema definition for the input parameters of the get_step_progress tool (executionId required, roleId optional) and its TypeScript type inference.

  const GetStepProgressInputSchema = z.object({
    executionId: z.string().describe('Execution ID for progress query'),
    roleId: z.string().optional().describe('Optional role ID filter'),
  });
  
  type GetStepGuidanceInput = z.infer<typeof GetStepGuidanceInputSchema>;
  type ReportStepCompletionInput = z.infer<
    typeof ReportStepCompletionInputSchema
  >;
  type GetStepProgressInput = z.infer<typeof GetStepProgressInputSchema>;